Glossary

The Babelize Glossary feature gives you control over how specific terms, brand names, and technical jargon are translated. By establishing a project glossary, you can prevent automatic translation of trademarked terms or enforce specific translations for key words.

Glossary Entry Types

You can define two types of glossary rules for any given term:

1. Never Translate

Used for words that must remain exactly as they are in the source text across all target languages.

• Examples: Brand names ("Babelize", "Stripe"), product names ("Pro Plan"), technical terms ("Next.js", "WebSocket").
• Behavior: The translation engine preserves the exact casing and characters of the term in all target locales.

2. Always Translate As

Used to map specific source terms to exact translations in target languages.

• Example: Translate the English word "workspace" always as "espace de travail" in French and "espacio de trabajo" in Spanish.
• Behavior: Uses the translation you specify for the term (see How It Works for how this differs between Babelize's translator and an LLM).

How It Works

graph TD
    A[Source Text] --> B[Protect placeholders, tags, URLs, code]
    B --> C[Protect glossary terms as tokens]
    C --> D[Translator]
    D --> E[Validate tokens, restore terms]
    E --> F[Final Translated Output]

1. Protect: Placeholders ({name}, %s), tags, URLs, emails and code are swapped for opaque tokens first, so a glossary term can never match inside them: a dashboard rule doesn't touch {dashboard} or https://example.com/dashboard.
2. Terms: Glossary terms are matched as whole words, ignoring case, in any script (Café matches, Cafés doesn't). "Never Translate" terms become tokens too and come back exactly as written in the source.
3. Translate and validate: Every token must come back exactly once, or the string is rejected and retried rather than shipped.
4. Always Translate As:
   • With Babelize's translator (dashboard runs, NLLB), the term is sent as a token and restored to your translation, so it is always used. The word around it isn't inflected for the sentence (no case endings added), which is the trade-off for a guaranteed term.
   • With an LLM (your own API key), the rules go into the prompt as required terminology, so the model can inflect them. If it doesn't use one, the string is flagged for review; the output is never rewritten after the fact.

A translation for pt also applies to pt-BR (an exact pt-BR entry wins), and locale codes are stored in their standard form (pt-BR, zh-Hant). If the same term is both "Never Translate" and "Always Translate As" (in any capitalization), "Never Translate" applies and the affected strings get a review note.

Editing the glossary

Translations Babelize already made are kept in the lockfile together with the glossary rules that applied to them. When you add, change or remove a rule, the next run re-translates exactly the strings that rule touches, in the languages it affects, and nothing else. Stored translations from translation memory or the cache are only reused if they follow the current glossary. Translations a person wrote into your project's own files (for example a Django .po catalogue) are never overwritten by a glossary change.

Local projects

babelize translate and babelize check read the glossary from .babelize/config.json:

{
  "glossary": {
    "neverTranslate": ["Babelize"],
    "alwaysTranslateAs": [{ "term": "workspace", "translations": { "fr": "espace de travail", "pt": "espaço de trabalho" } }]
  }
}

Managing Your Glossary

To manage glossary entries for a project:

1. Open your project in the dashboard.
2. Click the Glossary tab in the project navigation.
3. Add terms individually or upload a CSV file.

CSV Import / Export

You can bulk manage your glossary using CSV files (UTF-8):

term,type,es,fr
Babelize,never_translate,,
workspace,always_translate_as,espacio de trabajo,espace de travail

• Columns: term, type (never_translate or always_translate_as), then one column per locale code holding the translation. Cells written as fr:espace de travail are accepted too. Without a header row, every translation cell must use that locale:value form.

• Export: Export CSV downloads the whole glossary in exactly this format (with a UTF-8 byte-order mark so Excel shows non-Latin scripts correctly). Values a spreadsheet would read as a formula (starting with =, +, - or @) are prefixed with '; import removes that prefix again, so terms like -webkit or @handle round-trip unchanged.

• Import: Import CSV asks what to do with terms that already exist (matched regardless of letter case):

  • Update (default): the row's type wins, and its filled-in translations replace the stored ones; empty cells keep the stored translation. Export, edit, import works as expected.
  • Skip: only new terms are added.

  The result lists how many entries were added, updated, skipped and rejected, with the line number and reason for every rejected row (empty term, unknown type, duplicate term, value too long, …).

Limits

• Terms are unique per project regardless of letter case ("Dashboard" and "dashboard" are the same term).
• Terms and each translation: up to 200 characters, the most the hosted translator accepts per glossary item.
• Up to 5,000 entries per project (and per import). The hosted translator sends at most 50 glossary items with each translation batch.

Permissions

Viewers can read and export the glossary, editors can also add, edit and import entries, and admins and owners can delete them.

Plan Availability

The Glossary feature is available on all plans, including Free.