| name | intor-translate-locales |
| description | Translate Intor locale files from a default locale messages directory while preserving keys, structure, replacements, rich tags, ICU syntax, and file layout. |
Intor Locale Translation Skill
Use this skill when translating locale files for an Intor-based project.
The goal is to create or update target locale files by following the default locale messages directory as the source of truth.
Scope
This skill is for file-based locale translation workflows such as:
- Translate
./messages/en into ./messages/zh-TW
- Fill in missing locale files by mirroring the default locale folder structure
- Update existing translated files while preserving the Intor message shape
This skill is not for:
- Refactoring application code
- Renaming message keys
- Changing locale folder layout
- Rewriting translation semantics beyond the source meaning
Intor Guarantees
When working with Intor messages, always preserve the following:
- The default locale is the source of truth for message shape.
- Message keys must not be added, removed, or renamed.
- Nested object structure must remain identical.
- The target locale should mirror the default locale file layout unless explicitly instructed otherwise.
File Handling Rules
Treat the default locale messages directory as the canonical source.
Example:
- Default locale path:
./messages/en
- Target locale path:
./messages/zh-TW
Rules:
- Read the default locale files first.
- Mirror the same directory and file structure in the target locale.
- Process one message file at a time.
- Prefer JSON-based translation workflows for v1 unless the user explicitly asks for another format.
- Do not invent new files that do not exist in the default locale tree.
- If a target locale file does not exist, create it by following the default locale path.
Translation Rules
Translate only user-facing message text.
Never change:
- Message keys
- Object structure
- Placeholder names
- Rich text tag names
- ICU argument names
- ICU control syntax
- Markdown structure unless only the human-readable text is being translated
Preserve the meaning, tone, and formatting intent of the source text.
If a term is ambiguous:
- Prefer a conservative translation
- Preserve product names, API names, and brand names unless the user explicitly wants them localized
- Keep the original source text when uncertainty would otherwise break correctness
Prefer natural, product-quality phrasing over literal translation.
Rules:
- Translate for real user interfaces, not word-for-word parity.
- Preserve meaning, intent, and level of formality.
- Rewrite sentence order when needed for the target language, as long as structure and syntax constraints remain valid.
- Avoid awkward literal translations when a more natural equivalent exists.
- When the source text is simple UI copy, prefer concise and idiomatic target-language phrasing.
Replacements
Replacements are plain placeholders such as:
{name}
{count}
{price}
{date}
Rules:
- Preserve replacement names exactly.
- Do not translate replacement names.
- Do not remove or duplicate placeholders.
- Reorder surrounding words only if the target language requires it.
Examples:
"Welcome back, {name}!"
"You have {count} items."
"Price: {price}"
Rich Text
Rich text messages may contain tags such as:
<link>...</link>
<strong>...</strong>
<em>...</em>
<paragraph>...</paragraph>
Rules:
- Preserve tag names exactly.
- Preserve opening and closing tag balance.
- Translate only the human-readable text inside or around the tags.
- Do not replace rich tags with plain text.
- Do not convert plain text messages into rich text messages unless the source already uses rich tags.
Examples:
"Read our <link>documentation</link>."
"<strong>Welcome</strong> back, {name}!"
ICU Messages
ICU syntax must remain structurally valid.
Common ICU forms include:
- plural
- select
- selectordinal
- date/time/number formatting
Rules:
- Preserve the ICU message structure.
- Preserve argument names exactly.
- Translate only the human-readable branches and text fragments.
- Do not alter ICU keywords such as
plural, select, one, other, male, female.
- Do not remove required branches.
- When the target language needs a different natural phrasing, rewrite the branch text while keeping the ICU structure valid.
- Do not keep English-oriented phrasing patterns if they sound unnatural in the target language.
Examples:
"{count, plural, =0 {No messages} one {# message} other {# messages}}"
"{gender, select, male {He updated the document.} female {She updated the document.} other {They updated the document.}}"
"Total: {amount, number, ::currency/USD}"
Markdown Messages
Some message values may contain Markdown.
Rules:
- Preserve Markdown syntax and structure.
- Translate the readable text inside headings, lists, emphasis, and links.
- Do not corrupt Markdown formatting.
- Do not convert Markdown messages into plain text.
Localization Quality
Translations should feel like they were written for native speakers of the target locale.
Rules:
- Prefer natural phrasing over rigid source-language word order.
- Keep UI labels concise.
- Keep notifications clear and conversational.
- Keep validation messages direct and conventional for the target locale.
- Keep error messages short, precise, and user-friendly.
Examples:
- Prefer a natural equivalent of
"See you later" over a rigid literal translation.
- Prefer target-locale wording for ordinals, pluralized nouns, and system messages when the source language pattern does not map naturally.
Recommended Workflow
Follow this order:
- Identify the default locale directory and target locale directory.
- Enumerate the default locale files.
- For each file, read and parse the message content.
- Translate the content while preserving Intor structure and syntax rules.
- Write the translated content to the mirrored target locale path.
- Repeat until all files are processed.
- Validate the final target locale files if validation tooling is available.
- Review the output for awkward literal phrasing, especially in ICU branches and short UI labels.
Output Expectations
The final translated result should satisfy all of the following:
- Same keys as the default locale
- Same nested structure as the default locale
- Same placeholders, rich tags, and ICU argument names
- Same file layout as the default locale
- Natural target-language text for user-facing content
Hard Constraints
Never do any of the following:
- Rename keys
- Drop keys
- Add extra keys
- Break JSON syntax
- Break Markdown syntax
- Break rich tag structure
- Break ICU syntax
- Translate placeholder names
- Change file paths without explicit instruction
- Preserve awkward source-language wording when a natural target-language phrasing is possible without breaking structure
Decision Policy
When forced to choose between fluency and structural safety:
When forced to choose between a risky translation and preserving the source:
- Prefer preserving the source text
When a translation would require changing message structure:
- Do not change the structure