Some file formats support inline comments that the Lingo.dev CLI includes in translation requests. These comments provide context to the AI model - disambiguating terms, specifying tone, or describing where content appears in the UI.
Why translator notes matter#
The word "Records" can refer to medical records, music records, or database records. Without context, the AI model has to guess. A translator note eliminates the ambiguity:
{
// Medical context: refers to patient medical records
"records": "Records"
}The comment is sent alongside the string in the translation request, steering the model toward the correct interpretation.
Supported formats#
Translator notes are currently supported in:
| Format | Bucket type | Comment syntax |
|---|---|---|
| JSONC | jsonc | // comment above the key |
| Xcode String Catalogs | xcode-xcstrings | Comment field in the .xcstrings file |
JSONC example#
{
// Navigation menu item - appears in the top header bar
"nav.home": "Home",
// Button label - triggers form submission, keep it short
"form.submit": "Submit",
// "Light" refers to the visual theme, not weight or illumination
"settings.theme.light": "Light"
}To use JSONC, configure the jsonc bucket type in your i18n.json:
{
"buckets": {
"jsonc": {
"include": ["locales/[locale].jsonc"]
}
}
}Writing effective notes#
Effective translator notes describe context that isn't obvious from the string itself:
| Effective | Why |
|---|---|
// Button label in checkout flow | Tells the model about UI placement and expected brevity |
// "Set" means a collection, not the verb | Disambiguates a polysemous word |
// Formal tone - displayed in legal footer | Sets register expectations |
Notes that restate the string itself (// This says Welcome) don't add value.