Translator

Translator

Translate from one source language into one or more target languages while keeping proper nouns and special terms stable across future translations.

The main job of this skill is not only to translate well, but also to stop naming and terminology drift for glossary-worthy items. A person, product, team, brand, project, location, program, document title, feature label, or explicit special term should not be translated one way today and a different way later unless the user explicitly asks for a change.

Glossary memory

Use one writable glossary file in the working folder:

• ./translator-glossary.tsv

The glossary starts empty. Do not assume the file already exists.

Create translator-glossary.tsv only when a new proper noun, special term, or preferred rendering must be persisted for the first time.

The TSV schema is dynamic:

• one column per language, named by normalized short code such as ja, en, vi, fr
• fixed metadata columns at the end:
  • type
  • notes

Example header:

• ja
• vi
• en
• type
• notes

Each row represents one glossary-worthy item such as a proper noun, special term, or named concept.

• A populated language cell stores the preferred rendering in that language.
• A blank language cell means that rendering is not known yet.
• The same row can accumulate more language columns over time.

When this skill should act

Use this workflow when the user asks to:

• translate from one language into one or more other languages
• keep terminology or names consistent across messages
• build or maintain a bilingual or multilingual glossary
• reuse previous translations for names, products, brands, teams, screens, document titles, or explicit special terms

Workflow

Source, incrementality, and performance rules

• Translate from the current source content the user named. Do not fetch, restore, or use a target-language file from Git history, HEAD, or another previous version as the translation baseline unless the user explicitly asks to restore, compare, or reuse that prior version.
• If a target file already exists, use it only as an optional reference when the user asked for reuse or comparison. Otherwise, produce the target from the current source.
• Do not retranslate an entire file when the source changed only in part. Prefer an incremental workflow: extract stable text units, reuse exact existing translations from approved translation memory/cache or unchanged source units, translate only new or changed source units, then apply the merged mapping back to the document.
• For structured files such as HTML, Markdown tables, spreadsheets, slides, and extracted fragments, count human-visible source text before deciding whether to split work. Only split into chunks when there are more than 50k visible source characters after deduplication or when one model response cannot safely hold the mapping.
• Treat the 50k deduplicated visible-character threshold as a hard execution gate. If the count is at or below 50k, do the main translation pass single-pass in the current session. Do not use chunking, chunk workers, or subagents for the main translation mapping just for convenience, speed, or to avoid a long mapping; worker/subagent startup is part of the chunking workflow this rule is meant to prevent for medium files.
• When chunking is necessary, each subagent or chunk worker must write its translated mapping directly to a specified output file such as vi_chunk_N.tsv; do not ask workers to return long TSVs in chat and then do a second pass to save them.
• Prefer fewer, larger chunks over many small chunks. Chunking is for capacity, not for routine speed, because worker startup and coordination overhead can be slower than a single-pass translation for medium files.

1. Resolve the source language and target languages

Detect whether the request clearly specifies:

• source language
• one or more target languages
• mixed / bilingual cleanup

Accept either full language names or common codes such as Japanese / ja, Vietnamese / vi, English / en, French / fr.

Accept requests like:

• ja -> vi
• ja -> vi,en
• translate from Japanese to Vietnamese and English

If the source language is unclear, ask once before translating. If the target language list is unclear, ask once before translating.

2. Read the glossary if it exists

Before translating, try to read ./translator-glossary.tsv.

If the file does not exist yet:

• continue translating normally
• do not create the file unless a new term must be saved

If the file exists:

• treat each row as one multilingual glossary record
• match using the source language column for the current request
• for each requested target language, reuse the existing target-language cell when it is populated

3. Identify proper nouns and special terms before translating

Scan the source for glossary-worthy items that should stay stable across requests, especially:

• person names
• company / brand names
• product names
• project names
• team names
• place names
• event names
• feature names
• document or feature names used like titles
• explicit special terms the user asks to keep stable
• short labeled terms or canonical wording the user explicitly wants remembered

Do this before drafting the translations so the translations and glossary stay aligned.

Do not save ordinary vocabulary, common function words, or general sentence wording to the glossary just because they repeat.

4. Apply existing mappings exactly

If a row matches the source glossary item in the current source-language column:

• reuse each populated target-language cell exactly for the requested targets
• keep it consistent everywhere in that target output
• do not invent a second rendering for the same glossary item in that target output

Normalize only minor whitespace differences when matching. Do not silently replace one stored glossary item with a different one just because it sounds more natural in the moment.

5. Handle unseen proper nouns and special terms

If a glossary-worthy item is missing from the glossary, or an existing row lacks one of the requested target-language cells:

1. infer the best target-language form from the source and context
2. use that form consistently in the translation
3. after translating, persist it in ./translator-glossary.tsv

Persistence rules:

• if the file does not exist yet, create it only now
• initialize the header with the source language, all requested target languages, then type and notes
• if a later request introduces a new language, append that language column before type and notes
• if a matching row already exists, fill the missing target-language cell in that row
• if no matching row exists, create one new row and populate the source-language cell plus all requested target-language cells that were learned in this request
• one multi-target request should update one shared multilingual row per glossary item, not one row per target direction
• persist only glossary-worthy items such as proper nouns or explicit special terms, not ordinary words

Prefer official or already-obvious public forms when they are clear from the text. If there is no obvious official form, choose the most defensible natural rendering and make it canonical. For special terms, persist them only when the user explicitly signals they should be kept stable.

6. Update the glossary carefully

When adding or revising entries:

• keep the header row intact
• keep type and notes as the last columns
• avoid duplicate rows for the same glossary item
• preserve existing renderings unless the user explicitly asks to rename something
• rewrite the file in a clean, normalized state if needed instead of appending messy duplicates
• keep notes short and useful

Only change an existing rendering when one of these is true:

• the user explicitly requests a new preferred translation for that language
• the stored rendering is clearly wrong for the same glossary item

When updating one language for a glossary item, do not overwrite other populated language cells for that row.

7. Default output

If exactly one target language is requested, return only the translated text by default.

If multiple target languages are requested, return labeled sections in the same order requested by the user, for example:

## vi
<translated Vietnamese text>

## en
<translated English text>

Do not add commentary, glossary dumps, or translation notes unless:

• the user asks for them, or
• there is a genuine ambiguity that could change meaning materially

If there is a serious ambiguity, keep the note short and specific.

Translation guidance

• Keep meaning, tone, and intent intact.
• Prefer natural target-language phrasing for the sentence body.
• Keep proper nouns and special terms stable even when the surrounding sentence is heavily rewritten for fluency.
• Preserve honorific or register nuance only when it matters to meaning or tone.
• Do not over-literalize source-language sentence structure into the target language.
• Preserve the order of requested target languages in multi-target output.
• Treat each row as a shared multilingual record: adding a new language should extend the row, not duplicate it.
• If the content includes a Mermaid chart, make sure the translated Mermaid output still uses valid Mermaid syntax.
  • Always quote translated Mermaid node labels.
  • Never assume translated labels remain parse-safe.
  • Validate every Mermaid block after translation.
• If the user gives one input file, write the translated output to <parent-dir-of-input-file>/<translated_language_code>/<original-file-name> unless the user explicitly asks for a different output location or filename.
• If the user gives one input folder, find all text files in that folder tree such as Markdown files, translate them, and write outputs to <target-dir>/<translated_language_code>/<relative-path-from-input-folder>/<original-file-name>. If target-dir is not explicitly specified, use the input folder as the target dir root.
• When translating a folder tree, preserve the original relative subdirectory structure under <translated_language_code>/.
• After translating structured documents (HTML, Markdown tables, spreadsheets, slides, extracted fragments), run a language-agnostic token-boundary QA pass before completion:
  • Preserve markup/structure; inspect only human-visible text.
  • Catch glued or missing-separator boundaries between translated fragments, inline runs, glossary terms, acronyms, names, numbers, units, formulas, punctuation, CJK/Latin text, and technical/domain terms.
  • Fix only when the target language normally requires separation; do not add spaces blindly for scripts/languages that do not.
  • For folder translations, scan every generated file, including auxiliary and non-indexed outputs.
  • If unsure, report a possible boundary artifact instead of silently rewriting it.

Conflict handling

If the source text suggests two different glossary items with very similar names:

• do not merge them into one glossary row
• keep separate multilingual rows
• ask a clarification question only when the distinction is necessary to avoid a likely mistake

If the user asks to override a stored name for a specific document only, follow the request for that document and mention the glossary should be updated only if they want the new form to become the default.

Suggested response shapes

Single-target translation

Return only the translated text.

Multi-target translation

Use this format:

## <target_lang>
<translated text>

## <target_lang>
<translated text>

If the user asks for glossary visibility

Use this format:

## <target_lang>
<translated text>

### Glossary mappings used
- <source_lang>: <source_value> → <target_lang>: <target_value>
- <source_lang>: <source_value> → <target_lang>: <target_value>

Example

Example 1

Input: Translate from Japanese to Vietnamese and English: PhoenixチームはAsteria Pulse Reviewの検証を開始しました。

Output:

## vi
Đội Phoenix đã bắt đầu xác minh Asteria Pulse Review.

## en
The Phoenix team has started validating Asteria Pulse Review.

If the glossary file does not exist yet and Phoenixチーム or Asteria Pulse Review needs to be remembered, create ./translator-glossary.tsv in the working folder and add one multilingual row per glossary item with ja, vi, en, type, and notes columns.