Descriptions

A description is a short note attached to a translation key that gives extra context. It's especially useful for short or ambiguous keys, where the text alone isn't enough to translate correctly. For example, a key charge with value Charge could mean "charge the battery" or "charge a credit card", depending on context.

SimpleLocalize stores two separate descriptions for every translation key.

Code description

Written by developers, directly in source code or translation files. For example, the description field in the Browser extension JSON format, or a comment in gettext PO files. It's meant to travel with the code and update automatically as the codebase changes. It cannot be edited on UI, and it updates only on import.

Translator description

Written manually in the Translation Editor, usually by a translator or project manager, to clarify a key that doesn't have (or needs more than) a code description.

Why two fields instead of one?

Descriptions are kept separate so that re-uploading translations from your codebase never silently overwrites context a translator has manually added in the editor, and vice versa. Both can be shown in the Translation Editor.

How uploads map to each field

By default, a description found in a file uploaded via the CLI is saved as the code description only, and the translator description is left untouched.

Uploads from other sources write the description field straight to the translator description instead.

If you want a CLI upload to update the translator description rather than the code description, use the UPDATE_DESCRIPTIONS import option:

simplelocalize upload --apiKey <API_KEY> \
  --uploadPath ./path/to/translations.json \
  --uploadOptions UPDATE_DESCRIPTIONS

How downloads map to each field

Downloaded files don't include descriptions by default. Add the INCLUDE_DESCRIPTIONS export option to include them — by default this exports the translator description.

To export the code description instead, e.g. to get back exactly what's in your codebase, regardless of whether a translator has since added their own note you can combine it with USE_CODE_DESCRIPTIONS export option:

simplelocalize download --apiKey <API_KEY> \
  --downloadPath ./path/to/translations.json \
  --downloadOptions INCLUDE_DESCRIPTIONS,USE_CODE_DESCRIPTIONS

Descriptions are stored per translation key, not per language, so the exported description is the same regardless of which language you download.

Descriptions as AI context

Both code and translator descriptions are passed to the AI provider as context during auto-translation, helping it produce more accurate, disambiguated translations.