Translator notes in CLI v0
Put occurrence-specific meaning beside legacy JSONC or Xcode messages and refresh the affected translation deliberately.
A short label often omits the information a translator needs. A note can identify the subject, action, or register without adding visible words to the interface. In the legacy workflow, use JSONC comments or native Xcode catalog comment fields where supported.
Explain the missing meaning #
{
// Patient medical records, not music recordings
"records": "Records",
// Button that submits the form; use a short action label
"submit": "Submit",
// Visual theme, not weight
"theme.light": "Light"
}Select the commented parser in i18n.json:
{
"buckets": {
"jsonc": { "include": ["locales/[locale].jsonc"] }
}
}“Collection of saved medical records” resolves the subject. “Text shown to a user” does not. A placement and register note can explain why a formal notice differs from an action label. Use a key control for an exact value that must not change instead of relying on a linguistic note to protect it.
Inspect the affected result #
A note-only edit may not change the source value's checksum. Request selected retranslation when the installed version otherwise skips the unchanged text. Read the translated label in its actual surrounding interface.
For XCStrings, use the native comment field and preserve the shared catalog's locale structure. Check legacy formats before assuming another bucket reads notes the same way. These legacy comments are not the current React catalog's hash/context contract.
Keep an occurrence-specific note separate from localization engine-wide glossary, rules, and voice. Both can be sent to the backend, so neither should contain secrets or content you are not authorized to disclose.