# Translator > Translate from one source language into one or more target languages with stable glossary mapping for proper nouns and special terms. Use this skill whenever the user asks for translation, bilingual or multilingual copy adaptation, glossary harmonization, or wants names, brands, teams, products, projects, place names, or explicit special terms translated the same way across repeated requests. Also use it when the user asks to remember preferred translations for future multilingual work. - Skill: `tamntlib/translator` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tamntlib/translator` - Raw SKILL.md: https://api.skillmd.com/api/skills/tamntlib/translator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tamntlib (https://skillmd.com/u/tamntlib) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tamntlib/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: ```markdown ## vi ## en ``` 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 `//` 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 `///`. 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 `/`. - 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: ```markdown ## ## ``` ### If the user asks for glossary visibility Use this format: ```markdown ## ### Glossary mappings used - : → : - : → : ``` ## Example **Example 1** Input: Translate from Japanese to Vietnamese and English: `PhoenixチームはAsteria Pulse Reviewの検証を開始しました。` Output: ```markdown ## 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.