Translate

Translate (Plane i18n)

Single source of truth for turning English UI strings into every target locale under packages/i18n/src/locales/. Follow this skill exactly — every mistake here ships to every user in that language.

The locale list grows over time. This skill is intentionally generic: rules apply to any locale present now or added later. When you add a locale not explicitly named below, see Adding a locale not documented here at the bottom.

Sources distilled from: Microsoft Localization Style Guides, Mozilla L10n, Unicode CLDR plural rules, W3C i18n, Google developer style guide, Apple HIG, GitHub Primer, MQM error typology, Lokalise/Crowdin/Phrase best-practice docs, and Microsoft's AI/LLM-for-translation guidance.

Source of truth: packages/i18n/src/locales/en/<namespace>.json. Every other locale mirrors English key-for-key. The sync-check.ts script catches missing / stale / collision keys; it does not catch value-quality mistakes. That is what this skill is for.

When to Use

• Adding a new key to any packages/i18n/src/locales/en/*.json
• Renaming or rewording an English value (every target is now stale)
• Adding a new language (copy from en/, then translate each file)
• Syncing after pnpm --filter @plane/i18n run sync:check reports drift
• Reviewing any PR that touches packages/i18n/src/locales/

Skip only for trivial English-only typo fixes that don't change meaning or length meaningfully.

The Two Iron Rules

1. Trademarks, brand marks, plan tier names, third-party product names, acronyms, and code tokens are never translated. Plane's brand marks (Plane, Plane AI, Power K, PQL, Active Cycles, Sticky/Stickies, Intake), plan tiers (Pro, Business, Enterprise), third-party products (GitHub, Slack, Notion, etc.), and acronyms (API, OAuth, etc.) stay Latin in every locale.
2. CLDR plural categories are mandatory. Every target locale must include every plural keyword the language requires. Missing a form renders the wrong word at runtime and passes sync-check silently.

Common feature nouns — Cycle, Module, Epic, Page — are translated into the target language using the canonical glossary further down. They are not brand marks; they are everyday words that belong in the user's language.

The rest of this skill explains how to execute on those rules.

Do-Not-Translate (DNT) Glossary

For each term: the source, the required rendering per script group, and forbidden renderings that have appeared historically and must be reverted when seen.

Plane brand & features

Plane feature noun translation glossary (translate, do not preserve)

These are common nouns. Translate them into the target language using the canonical form below. This follows Microsoft, Apple, and Mozilla style guides for product-UI translation: feature common nouns belong in the user's language; only trademarks, brand marks, and acronyms stay Latin. Leaving these in Latin in non-Latin locales reads as half-translated and is a measurable quality defect.

Use the table verbatim — never coin new variants; never leave the Latin form in the locale value.

Notes:

• Single-form locales (zh-CN, zh-TW, ja, ko, vi-VN, id) use the same form for singular and plural — the column repeats by design.
• Slavic locales (ru, ua, pl, cs, sk) show nominative singular and nominative plural. Inside ICU {count, plural, ...} blocks, use the case-correct form per CLDR keyword (see the Slavic case-form table further down).
• Some Latin locales (fr, vi-VN, id) have forms identical to English (Cycle, Module, Page) — that's the natural cognate, not a Latin-preservation rule.
• Epic / Epics: stays Latin in most Latin locales because there's no clean cognate (Spanish épico is for poetry/film; same for it/pt-BR/de/fr). Slavic locales use phonetic transliteration that's standard in their software industry (Эпик, Епік, Epik). CJK locales use the literal/transliterated form (史诗, エピック, 에픽).
• Generic uses translate normally and don't follow this glossary: next page (paginator), the page (browser refresh), status page, web page, life cycle, release cycle, rate-limit cycle, cycle of releases — these are not the Plane Cycle/Page feature; translate them as ordinary words in the surrounding prose.
• When editing an existing file, migrate occurrences you are already touching. Do not bulk-rewrite unrelated strings in the same PR — land a separate sweep PR with the chore(i18n): prefix.

Slavic case forms inside ICU plural blocks

When a Slavic plural block counts a Plane feature noun, use these forms:

Per CLDR for ru/ua: one fires for 1, 21, 31… (nom.sg.); few for 2–4, 22–24… (gen.sg.); many for 0, 5–20, 25–30… (gen.pl.); other for non-integer counts (gen.sg.). For pl: one (1), few (2–4 not 12–14, nom.pl.), many (0, 5–20, gen.pl.), other (decimals, gen.sg.). cs/sk: one (1), few (2–4, nom.pl.), many (decimals, gen.sg.), other (0, 5+, gen.pl.).

Third-party products & standards (always Latin, every locale)

GitHub, GitLab, Bitbucket, Slack, Discord, Zoom, Microsoft Teams, Jira, Linear, Asana, Notion, Confluence, Trello, Figma, Google, Google Drive, Google Calendar, Google Docs, Google Sheets, Gmail, YouTube, Dropbox, Zapier, Tiptap, ProseMirror, Yjs, Hocuspocus, Socket.IO, React, TypeScript, JavaScript, Python, Django, PostgreSQL, Redis, RabbitMQ.

Also preserve: OAuth, OIDC, SAML, SSO, LDAP, API, REST, GraphQL, URL, URI, ID, UUID, JSON, YAML, CSV, TSV, XML, HTML, PDF, PNG, JPG, SVG, CSS, HTTP, HTTPS, TLS, SSL, IP, CIDR, DNS, ARIA, WCAG.

Inside-string tokens (mechanical — preserve exactly)

• ICU variables: {count}, {name}, {workspace}, {userName} — never translate, never rename, never move inside {}.
• ICU pluralization / select keywords: plural, select, one, few, many, other, zero, two, =0, =1, # — never translate.
• HTML & JSX tags: <b>…</b>, <a href="…">…</a>, <br/>, <code>…</code> — preserve attributes and nesting; translate only the visible text between tags.
• i18next Trans numbered fragments: <0>…</0>, <1>…</1> — preserve the numbers exactly; only translate the wrapped text. Never renumber.
• Markdown: **bold**, *italic*, `code`, [text](url) — keep the syntax; translate only human-readable prose.
• Escape sequences: \n (newline), \t, \", \\ — preserve at the same positions.
• Keyboard keys & modifiers: Ctrl, Cmd, Shift, Alt, Option, Enter, Return, Esc, Tab, Space, Backspace, arrow glyphs (↑↓←→), and OS glyphs (⌘⌥⌃⇧) — preserve exactly as shown on the physical key.
• File extensions & formats: .json, .csv, MM/DD/YYYY format strings — preserve.

Per-Script Rules

Apply by target-language script, not by locale list. Adding a new Latin-script locale? It follows the Latin-script rules below. Adding a new Cyrillic locale? It follows the Cyrillic section. Scripts not yet shown here (Arabic, Hebrew, Thai, Greek, Hindi/Devanagari, etc.) — see Adding a locale not documented here.

Latin-script locales

Currently includes fr, es, it, de, pt-BR, pl, cs, sk, ro, tr-TR, vi-VN, id — and any future locale that uses the Latin alphabet (hu, nl, sv, da, nb, fi, hr, bg-using-Latin variants, etc.).

Translate Plane feature nouns (Cycle, Cycles, Module, Modules, Epic, Epics, Page, Pages) using the per-locale form from the glossary above. Keep Latin for Plane brand marks (Plane, Plane AI, Power K, PQL, Active Cycles, Sticky, Stickies, Intake), plan tier names (Pro, Business, Enterprise), and third-party brands (GitHub, Slack, etc.).

✅ "Créer un Cycle"                         (fr — natural cognate from glossary, identical to English)
✅ "Crear un nuevo Ciclo"                   (es — natural Spanish cognate from glossary)
✅ "Archiviare questo Modulo"               (it — natural Italian cognate from glossary)
✅ "Nueva Epic"                             (es — Epic has no clean cognate; stays Latin per glossary)
✅ "Archivieren Sie diesen Zyklus"          (de — natural German form from glossary)
✅ "Buat Siklus baru"                       (id — natural Indonesian form from glossary)
✅ "Buat Sticky baru"                       (id — Sticky is a Plane brand mark, stays Latin)
✅ "Wechseln Sie zum Pro-Plan"              (de — Pro is a plan tier name, stays Latin)
❌ "Créer un Cycle"                         WRONG when the locale should be `Zyklus` (de). Always use the glossary form.
❌ "Archivieren Sie diesen Cycle"           (de — feature noun was left in Latin; use Zyklus per glossary)
❌ "Créer un Cercle"                        (fr — invented translation; use the glossary form)
❌ "Nueva Saga"                             (es — translated "Epic" with the wrong cognate)
❌ "Buat Catatan Tempel"                    (id — translated "Sticky" which is a brand mark; keep Latin)

Generic uses translate normally and do not follow the glossary: a paginator's next page is nächste Seite / página siguiente (generic noun, not the Plane Pages feature). The glossary applies only when EN refers to the Plane product feature.

Japanese (ja) — natural Japanese rendering

Plane feature nouns (Cycle, Module, Epic, Page) use the natural Japanese form per the glossary above (サイクル, モジュール, エピック, ページ — katakana for foreign-origin nouns; native Japanese where one applies, like 付箋 for an Apple/Microsoft-style "sticky note"). Brand marks stay in Latin: Plane, Plane AI, Power K, PQL, Active Cycles, Sticky, Stickies, Intake, GitHub, Slack, Pro/Business/Enterprise.

For new katakana coinages and existing translations, the long-vowel mark ー is added for words ending in -er, -or, -ar, -y in English. This is the Microsoft Japanese style-guide convention and the current industry default:

• user → ユーザー (not ユーザ)
• server → サーバー (not サーバ)
• editor → エディター (not エディタ)
• property → プロパティー (kept as プロパティ where the existing codebase already does — match the surrounding file's convention)

Tone: polite form です・ます. Never plain form だ・である. Avoid over-formal 尊敬語・謙譲語 for SaaS product copy — it reads stilted.

Quotation marks: 「」 for primary quotes, 『』 for nested or for titles of works. Full-width punctuation: 。、（）・！？.

Korean (ko) — Hangul rendering

Plane feature nouns (Cycle, Module, Epic, Page) use the natural Korean form per the glossary above (사이클, 모듈, 에픽, 페이지 — Hangul transliteration where the term is product-coined; native Korean word where one applies). Brand marks stay in Latin: Plane, Plane AI, Power K, PQL, Active Cycles, Sticky, Stickies, Intake, GitHub, Slack, Pro/Business/Enterprise.

For new terms not on the glossary: prefer the native Korean word where one exists (설정 for Settings); use Hangul phonetic transliteration for product-coined nouns with no native equivalent. Do not coerce a phonetic loanword when a natural Korean word exists — 버킷 for "Bucket" reads as a foreign trademark, 장바구니 reads as a Korean noun.

Korean particle agreement: when introducing a consonant-ending noun (사이클, 에픽, 모듈), follow with the consonant-form particle (을/은/이/과), not the vowel-form (를/는/가/와). 사이클을 추가 not 사이클를 추가.

Register:

• System and error messages → 합니다체 (high-formal: 합니다, 됩니다, 입니다). Existing files in this register today: ko/auth.json, ko/error/*.json.
• Empty states, onboarding microcopy, tooltips → 해요체 acceptable (softer: 해요, 돼요, 이에요) if the existing file uses it. Existing files in this register today: ko/empty-state.json, ko/tour.json. Always match the surrounding file rather than introducing a new register mid-namespace.
• Never casual 반말.

Punctuation: Western punctuation (. , ? !); straight quotes "…" and '…'.

Simplified Chinese (zh-CN) and Traditional Chinese (zh-TW) — translate feature nouns

Plane feature nouns (Cycle, Module, Epic, Page) translate to natural Chinese per the glossary above (zh-CN: 周期, 模块, 史诗, 页面 — zh-TW: 週期, 模組, 史詩, 頁面). This is what Microsoft's zh-CN style guide and every mainstream zh-localized SaaS product (Notion, Slack, Atlassian) does for common feature nouns.

Brand marks stay Latin: Plane, Plane AI, Power K, PQL, Active Cycles, Sticky, Stickies, Intake, GitHub, Slack, Pro/Business/Enterprise — these are trademark-style terms.

Insert a half-width space on each side of embedded Latin tokens — this is Microsoft's zh-CN guideline and required for legibility. Exception: no space between a Latin token and adjacent full-width punctuation (。，；：？！); the punctuation already supplies visual breathing room.

✅ "使用 GitHub 登录"           (Latin brand → half-width spaces around)
✅ "创建周期"                    (zh-CN feature noun translated; no Latin = no spaces)
✅ "归档此史诗"                  (Plane Epic → 史诗 per glossary)
✅ "添加 Sticky"                (Sticky is a brand mark → Latin + half-width space)
✅ "升级到 Pro"                 (Pro is a plan tier → Latin)
✅ "登录 GitHub。"               (no space between Latin token and full-width period)
❌ "使用GitHub登录"               (Latin brand without surrounding half-width space)
❌ "创建 Cycle"                   (feature noun left in Latin — should be 周期)
❌ "创建Cycle"                    (feature noun in Latin AND missing space)
❌ "登录 GitHub 。"               (stray space before full-width period)
❌ "创建赛克"                     (invented transliteration of Cycle — use the glossary's 周期)

Punctuation is full-width: 。，？！；：. Quotes:

• zh-CN: "…" (primary) and '…' (nested)
• zh-TW: 「…」 (primary) and 『…』 (nested)
• Work titles (book/movie/app/article names): 《…》

Variant discipline: zh-CN ≠ zh-TW. They differ in script (简体 vs 繁體) and vocabulary (视频 vs 影片; 软件 vs 軟體; 网络 vs 網路). Never mass-copy between the two directories.

Register: 您 (formal polite) in Plane UI — the product is B2B/SaaS. Reserve 你 for consumer/youth contexts (not applicable here).

Cyrillic locales

Currently includes ru, ua — and any future Cyrillic locale (bg-BG, sr-Cyrl, mk, be, kk-Cyrl, etc.).

Plane feature nouns (Cycle, Module, Epic, Page) use the natural Cyrillic form per the glossary above (Цикл/Циклы, Модуль/Модули, Эпик/Эпики, Страница/Страницы in ru — Цикл/Цикли, Модуль/Модулі, Епік/Епіки, Сторінка/Сторінки in ua). Brand marks stay in Latin: Plane, Plane AI, Power K, PQL, Active Cycles, Sticky, Stickies, Intake, GitHub, Slack, Pro/Business/Enterprise.

For new terms not on the glossary: prefer the native Cyrillic word where one exists; use phonetic transliteration only when no native word applies (Бакет is wrong for "Bucket" — use Корзина/Кошик).

Slavic case forms inside {count, plural, ...} blocks are case-correct per CLDR keyword (one=nom.sg., few=gen.sg., many=gen.pl., other=gen.sg.). See the case-form table in the glossary section.

Register:

• ru: formal Вы (capitalized) when addressing a single user directly in respectful/formal contexts (onboarding, settings, confirmation dialogs); lowercase вы for plural/general references ("все вы"). Default to capitalized Вы in tooltips/dialogs and lowercase вы in descriptive copy.
• ua: modern Ukrainian software convention is lowercase ви by default; capitalized Ви is reserved for very formal direct address. This is the opposite convention from Russian — do not copy-paste Russian capitalization rules into Ukrainian files.

Punctuation: primary quotes «…», nested „…".

Plural forms — critical: both ru and ua require one / few / many / other. See CLDR section below.

CLDR Plural Rules

Every {count, plural, …} string must contain every keyword the target language's CLDR rule requires. other is always required, even in single-form languages.

Canonical source: Unicode CLDR Language Plural Rules chart — the definitive, versioned list of required categories for every language. Always verify against the current CLDR chart when adding a locale, since rules occasionally shift across CLDR releases. Libraries like Intl.PluralRules can resolve the rule at runtime.

Below are the required keywords for locales currently in the repo. When adding a new locale, look up its categories in CLDR and add the row here.

Note on the consolidated row. CLDR itself only requires other for tr-TR, vi-VN, id, ja, ko, zh-CN, zh-TW (single-form locales). Emitting both one and other with identical content is a project convention — it keeps tooling and linters consistent across the codebase. It is not a CLDR requirement, and Intl.PluralRules will return only "other" for these locales at runtime.

For any locale not listed: look up the CLDR categories before writing a single plural string. Arabic has six; Welsh has six; most Slavic languages have four; most Romance languages have two or three; CJK / Turkic / Thai have one (still emit other).

Rules in practice:

1. Never drop a required form, even when the word is identical across forms — emit each one explicitly.
2. Never add a form the target doesn't have. German does not use few. Any few clause in de/*.json is a bug and must be removed.
3. In single-form locales (ja/ko/zh/tr/vi/id), emit one + other with identical content so tooling and linters stay consistent.
4. The other case is always the fallback — it must render a grammatically complete sentence on its own.

Examples:

// ✅ Correct — Russian (four forms; `other` fires for non-integer counts and takes genitive singular)
"members": "{count, plural, one {# участник} few {# участника} many {# участников} other {# участника}}"

// ✅ Correct — Polish (four forms)
"items": "{count, plural, one {# element} few {# elementy} many {# elementów} other {# elementu}}"

// ✅ Correct — Romanian (three forms)
"days": "{count, plural, one {# zi} few {# zile} other {# de zile}}"

// ✅ Correct — French (three forms; `many` covers 1 000 000, 2 000 000, …)
"members": "{count, plural, one {# membre} many {# membres} other {# membres}}"

// ✅ Correct — Japanese (single form, both keywords emitted)
"label": "{count, plural, one {サイクル} other {サイクル}}"

// ❌ Wrong — German with spurious `few`
"label": "{count, plural, one {Zyklus} few {Zyklen} other {Zyklen}}"

// ❌ Wrong — Russian missing `few` and `many`
"label": "{count, plural, one {Цикл} other {Циклы}}"

Placeholders, HTML, Markdown (preservation checklist)

For every translated string, verify before saving:

• Identical set of {variables} in source and target (character-for-character — {userName} is not {username})
• Identical HTML/JSX tags with identical attributes and nesting
• Identical i18next Trans numbered tags (<0>…</0>, <1>…</1> — never renumber)
• Identical Markdown syntax (**bold**, `code`, [link text](url))
• Identical \n positions (layout relies on these)
• No additions (no extra explanatory words), no omissions (no collapsed clauses)

Variables may be repositioned for grammatical fit:

en:  "Welcome, {name}! You have {count} new work items."
fr:  "Bienvenue, {name} ! Vous avez {count} nouveaux work items."
ja:  "{name}さん、ようこそ。{count}件の新しい作業項目があります。"

Per-Locale Punctuation & Spacing

Apply in every translated string. These are MQM "Locale Conventions" violations when missed — a measurable quality defect.

Table below covers locales currently in the repo; add a row when you add a locale.

Tone & Register (SaaS defaults)

Formality defaults for locales currently in the repo. Add a row for each new locale, consulting the Microsoft Style Guide for that locale as the default authority on product-UI register.

General writing rules (apply across all locales):

• Sentence case in buttons, headings, tooltips — not Title Case. Only capitalize proper nouns.
• No exclamation marks except in genuine celebrations (first success, milestone).
• No emoji in UI copy.
• No slang, idioms, humor, cultural references — they don't translate.
• Consistent terminology — if "work item" is used once, never switch to "issue" / "ticket" mid-flow.
• Active voice, present tense.
• Write out abbreviations on first use if not on the DNT list.

Text Expansion Budget

Design strings knowing translations will grow. Typical expansion vs. English for locales currently in the repo; lookup values from Andiamo / Eriksen / W3C tables when adding a locale.

Rule of thumb: any UI surface must absorb +35% without truncation. If a string is length-capped, add a comment or context in the source.

Numbers, Dates, Currency, Units

Never hard-code formats. Use ICU skeletons so the runtime localizes automatically:

"updated_on": "Updated {date, date, medium}",
"percent_done": "{ratio, number, percent} complete",
"item_count": "{count, number} items"

Never write "{date}MM/DD/YYYY" in the source — that guarantees a locale bug.

Decimal/thousands separators (runtime-handled):

• en: 1,234.56 — de/it/es/pt-BR/ru/ua/pl/cs/sk/tr-TR: 1.234,56 or 1 234,56 — fr: 1 234,56 (thin space) — ja/ko/zh: 1,234.56.

Date formats (runtime-handled):

• en-US: MM/DD/YYYY — most of Europe: `D

…(truncated)