game-localization
Skill26 starsChanged yesterdayMITView on GitHub
Covers localizing a browser game written in TypeScript: string tables with stable IDs, plurals and formatting through the Intl API, message format choice, text expansion, canvas text, right-to-left and CJK layout, fonts, pseudo-localization and the translation process. Use when a game will ship in more than one language, when you add dialogue, HUD labels, quest text or other player-facing strings that will be translated, or when text overflows, wraps badly or shows the wrong plural in another language.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- superwyh/Game-Localization-Engineeringtheir own version, first seen Nov 15, 2026
- jammyfu/open-game-skillstheir own version, first seen Oct 11, 2026
- pcmxiao/game-localizationtheir own version, first seen Oct 8, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- jammyfu/open-game-skills★ 13same name
- superwyh/Game-Localization-Engineering★ 7same name
- pcmxiao/game-localization★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository46 other files it gives its agents.
- asaasSkill
- betterauth-integrationSkill
- bullmq-game-queuesSkill
- character-design-narrativeSkill
- ci-cd-gameSkill
- claude-agent-sdkSkill
- database-performance-tuningSkill
- elevenlabs-sound-musicSkill
- foundry-vtt-devSkill
- game-anti-cheatSkill
- game-backend-architectureSkill
- game-blenderSkill
- game-clientSkill
- game-design-fundamentalsSkill
- game-architectSkill
- game-balanceSkill
- game-buildSkill
- game-expandSkill
- game-loreSkill
- game-questSkill
- game-reviewSkill
- game-devSkill
- game-economy-designSkill
- game-godotSkill
- gameplay-analyticsSkill
- game-save-loadSkill
- game-state-syncSkill
- game-unitySkill
- judgeSkill
- level-designSkill
- matchmaking-systemSkill
- mmo-designSkill
- monitoring-game-opsSkill
- nuvemshop-sdkSkill
- openclaw-genieSkill
- postgres-game-schemaSkill
- procedural-genSkill
- quest-mission-designSkill
- quest-narrative-coherenceSkill
- react-animationsSkill
- redis-game-patternsSkill
- skill-progression-treesSkill
- story-structure-gameSkill
- stripe-game-paymentsSkill
- ui-ux-gameSkill
- worldbuildingSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 0 are common, 10 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Keep every player-facing string in a resource file per language.
- Distinctive: line 15
When a string's meaning changes, give it a new ID, so old translations stop matching and translators see it as new (Mozilla).
- Distinctive: line 16
Never reuse one string in two places.
- Very specific: line 18
Never build a sentence from fragments.
- Distinctive: line 19
When an inserted part cannot agree with the fixed text (item names in loot toasts, quest names in log lines), use a topic-comment layout: …
- Distinctive: line 21
Prefer repeating text across messages to sharing fragments.
- Distinctive: line 22
Keep brand names and glossary terms as referenced terms, so one change updates every message (Fluent terms).
- Distinctive: line 30
Treat regional variants as separate locales: pt and pt-BR, es and es-419, zh-Hans and zh-Hant.
- Very specific: line 31
Use BCP 47 tags inside the game.
- Distinctive: line 56
Test plural messages with 0, 1, 2, 3, 5, 11, 21, 100 and 1000000 in every shipped locale.
- Very specific: line 66
Every line should print true, then few one and all four locales.
- Distinctive: line 77
No native JavaScript message formatter ships today: ICU MessageFormat, Fluent and MF2 all need a library on Bun and in browsers.
- Very specific: line 85
Read references/text-layout.md when you lay out HUD, menus, dialogue boxes or subtitles for more than one language: expansion budgets, …
- Distinctive: line 89
Run a pseudo locale from the first build, before any translation (Microsoft).
- Very specific: line 103
Read references/process.md when you plan translation work or a content patch: glossary and style guide, context for translators, string …
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Game localization
Internationalize from the first string: externalize text, format through Intl, and turn on a pseudo locale. Translation comes later and costs far less when the code is ready for it.
Strings: IDs, comments, whole messages
- Keep every player-facing string in a resource file per language. Hard-coded text sends translators into source code, where they can break it (IGDA). The client bundle and any server renderer read the same catalog files.
- Key messages by stable semantic IDs (
quest.ruins.offer,hud.gold.label), not by the English text. One English string can need different translations: Mozilla's example is "bookmark" as noun and verb, and Godot notes the same ambiguity with plain-English source strings, as opposed to message codes. - When a string's meaning changes, give it a new ID, so old translations stop matching and translators see it as new (Mozilla). Fixing a typo keeps the ID.
- Never reuse one string in two places. A noun and a verb that look the same in English get two entries (Mozilla).
- Give each message a translator comment: where it shows, what each placeholder holds, what must stay untranslated, and a length budget for fixed-size UI. Keep it in the catalog next to the message, not in code the translator never sees. Fluent binds a comment placed right above a message to it, and tools show both together.
- Never build a sentence from fragments. Write one message with named placeholders, so translators can reorder the pieces (ICU, Mozilla). Ban template-literal sentences such as
`${name} found ${n} ${item}`in client and server code. - When an inserted part cannot agree with the fixed text (item names in loot toasts, quest names in log lines), use a topic-comment layout: "Picked up: {item}", not "You picked up a {item}". The fixed text then needs no gender or number agreement (W3C).
- Inside plural or select messages, write a full sentence in each branch. Put select outside and nest plural inside it (ICU).
- Prefer repeating text across messages to sharing fragments. Use variants only for grammar, and separate messages for UI logic (Fluent good practices).
- Keep brand names and glossary terms as referenced terms, so one change updates every message (Fluent terms).
Copy boilerplate/string-table.ts when you need a typed string table: IDs typed from the source table, a comment and optional length budget on every entry, plural messages that require other, the fallback chain below, catalogs loaded in parallel, and failed loads recorded in loadErrors instead of failing the whole table. Its {name} placeholders and plural maps are a minimal stand-in, not ICU MessageFormat. Move to a real message format when a message needs gender or nested choices.
Locale fallback chain
Resolve from most to least specific, then the default locale: zh-Hans-CN, zh-CN, zh-Hans, zh, then en. Unreal processes cultures in that order. Add the likely script for a tag that has only a region, so zh-TW reaches a zh-Hant catalog (zh-TW, zh-Hant-TW, zh-Hant, then en). Skip the bare language when its likely script differs from the requested one: a bare zh catalog is usually Simplified and a bare sr one Cyrillic, so zh-TW and sr-Latn must not fall back to them. That skip is this skill's rule. The boilerplate does both with Intl.Locale.prototype.maximize(). Unity lets each locale list its fallbacks. Godot falls back to a project fallback locale, or to en.
- Treat regional variants as separate locales: pt and pt-BR, es and es-419, zh-Hans and zh-Hant. Steam lists Portuguese and Portuguese-Brazil, and Spanish-Spain and Spanish-Latin America, as separate languages.
- Use BCP 47 tags inside the game. Convert at the platform edge: Steam's API codes map
brazilianto pt-BR,latamto es-419,schineseto zh-CN. - Resolve the chain once per message ID when the catalogs load, and log misses and failed loads in development. The boilerplate does both.
- Intl throws RangeError on an invalid tag, currency code or time zone. On a server, parse the Accept-Language header, resolve it against the list of locales you ship, and pass only a shipped locale to the translator and the format helpers. Never pass a raw header value: distinct tags would also grow formatter caches. The boilerplate's cache keys on the locale's base name and holds at most 256 formatters (this skill's default).
- Format plurals and numbers with the locale the text came from. A Russian player who falls back to English text should not get Russian plural categories applied to English branches.
Plurals and formatting: use Intl
Do not hard-code singular and plural. CLDR gives English one and other; Russian and Polish one, few, many and other; Arabic all six categories; Japanese only other. Brazilian Portuguese (pt) and French put 0 in one; European Portuguese (pt-PT) does not. Every plural or select message needs a default branch: other in ICU syntax, * in Fluent.
| Need | Intl member | Note |
| Plural branch, 1st/2nd/3rd | Intl.PluralRules | type: 'ordinal' for ordinals |
| Counts, HUD numbers | Intl.NumberFormat | notation: 'compact' for short forms |
| Real money | Intl.NumberFormat | style: 'currency' has no default currency; pass an ISO 4217 code |
| Event times | Intl.DateTimeFormat | set timeZone to the player's zone; formatRange for windows |
| "in 3 days", "yesterday" | Intl.RelativeTimeFormat | you pick the unit; numeric: 'auto' gives words |
| Reward lists, party names | Intl.ListFormat | conjunction, disjunction or unit; never join with ", " and " and " |
| Name length, truncation, wrapping | Intl.Segmenter | grapheme for length, word for Japanese, Chinese, Thai |
| Sorting names | Intl.Collator | leaderboards, inventories |
| Language picker | Intl.DisplayNames | language names in their own language |
In-game soft currency (gold, gems) is not ISO 4217. Format the number with NumberFormat and put the currency word in the message, where it can take a plural.
Copy boilerplate/intl-format.ts when you need these helpers with cached formatters: plural and ordinal category, compact numbers, money, lists, event windows in the player's zone, relative time with the unit picked for you, grapheme truncation, canvas word wrap, name sorting and language names.
Test plural messages with 0, 1, 2, 3, 5, 11, 21, 100 and 1000000 in every shipped locale. Those numbers hit different categories across Arabic, Russian, Polish, both Portuguese variants and French.
Check Intl on the server runtime
Browsers have these members: MDN marks Intl.PluralRules baseline since September 2019, RelativeTimeFormat since September 2020, ListFormat since April 2021 and Segmenter since April 2024. Bun's Web APIs page does not list Intl. Before server code relies on Intl, run this on the target Bun version:
bun -e 'for (const k of ["PluralRules","NumberFormat","DateTimeFormat","ListFormat","RelativeTimeFormat","Segmenter","DisplayNames","Collator"]) console.log(k, k in Intl); console.log(new Intl.PluralRules("ar").select(3), new Intl.PluralRules("pt").select(0), Intl.DateTimeFormat.supportedLocalesOf(["ar","ja","th","pt-BR"]))'Every line should print true, then few one and all four locales. On Bun 1.4.4 on 2026-11-14 it did. That is one observation, not a documented guarantee: run it again in CI on the version you deploy, and add your shipped locales to the list.
Message format choice
| Option | Status checked 2026-11-14 | Pick when |
The boilerplate's {name} plus plural map | Code in this skill | Few plural strings, no gender, no nested choices |
| ICU MessageFormat (classic) | ICU documents plural and select arguments and full-sentence branches | Many plural or gender messages, translators or tools that already read ICU syntax |
| Fluent | Comments bound to messages, terms with variants, required default variant | Text-heavy games with brand terms and grammar that varies by language |
| MessageFormat 2 | Unicode TR35 Part 9, CLDR 49, stable; functions marked Draft may still change. In ICU4C and ICU4J. The TC39 Intl.MessageFormat proposal is at Stage 1 | A JS library you choose supports it; do not wait for native support |
No native JavaScript message formatter ships today: ICU MessageFormat, Fluent and MF2 all need a library on Bun and in browsers. Pick the library from its own documentation and pin its version. This skill names none because none was checked.
Text, layout, scripts and fonts
Short strings grow the most. W3C, quoting IBM, gives 200 to 300 percent for English strings of up to 10 characters and about 130 percent for strings over 70. Buttons and HUD labels break first. Let text reflow and avoid small fixed-width boxes.
Canvas fillText never wraps; its maxWidth squeezes or shrinks the text instead. Wrap with wrapLines from the boilerplate, or draw long text in DOM overlays. In a DOM overlay, insert translated text and player names with textContent, never innerHTML: a catalog or a player name can carry markup. That is this skill's own rule.
Read references/text-layout.md when you lay out HUD, menus, dialogue boxes or subtitles for more than one language: expansion budgets, canvas wrapping, right-to-left and bidi, CJK and Thai line breaking, French punctuation, fonts and glyph coverage, text in images and video, player names.
Pseudo-localization from day one
Run a pseudo locale from the first build, before any translation (Microsoft). It shows:
- strings missing from the catalog: they appear plain, untransformed;
- truncation and overflow: padding lengthens text (Microsoft suggests 40 percent) and a cut-off bracket shows where;
- concatenation: two bracket pairs inside one label;
- font gaps: accented letters the font cannot draw;
- right-to-left layout bugs: mirrored text (Unity's Mirror, Godot's
fake_bidi).
Name the pseudo locale with a tag that is not a real language. Microsoft once used tk-TM; when Windows later shipped Turkmen, the clash caused bugs. ICU reserves en-XA (accents) and en-XB (bidi); Windows uses the qps- range.
Copy boilerplate/pseudo-localize.ts when you add the pseudo locale: it accents letters, pads, brackets, optionally mirrors, keeps {placeholders}, tags, entities and printf tokens intact, and builds a catalog under en-XA from the source table. It understands only this boilerplate's {name} syntax; for ICU or Fluent messages use the library's own pseudo-locale, since this one would accent ICU keywords such as plural and one. Intl resolves en-XA to en (checked on Bun 1.4.4), so numbers and plurals format as English. Serve it in development builds only.
Process
Read references/process.md when you plan translation work or a content patch: glossary and style guide, context for translators, string freeze, the live-game cycle, LQA and culturalization.
The short version: give translators builds, context, a glossary, a style guide and name pronunciations before they start; freeze source text on a date the team commits to; run each live content patch as its own small localization cycle; regress localization fixes on more than one build; let the lead translator make the final call; change as little content as possible when culturalizing.
Store pages and in-game text are separate jobs. Steam decides language support from the in-game language settings, not the store page, and declares it per language as Interface, Full Audio or Subtitles.
Pitfalls
- Fixing a meaning change in place, so old translations still match the ID (rule 3).
- A template literal or
+joining translated pieces anywhere in UI code (rule 6). Search for it in review. - Sizing UI for English, or for an average 30 to 40 percent, when short labels grow 200 to 300 percent (W3C).
- Assuming one/other plurals, or that pt and pt-PT share rules: pt puts 0 in
one, pt-PT does not (CLDR). - Splitting text on spaces: breaks Japanese, Chinese and Thai (MDN
Intl.Segmenter). Slicing by code units splits emoji and accented letters; count graphemes. - Relying on canvas
fillTextto wrap (MDN). - Setting direction in CSS, or aligning left and right, for right-to-left text (W3C).
- Inserting a player name into right-to-left text without isolation (W3C).
- One CJK font for both Chinese and Japanese (W3C).
- A default font that cannot draw the target scripts (Godot).
- Text burned into textures or video (IGDA).
- A real locale code as the pseudo locale (Microsoft).
- Translating while the source text still changes (IGDA).
- Server code that formats with Intl on a runtime nobody checked.
Files
boilerplate/string-table.ts: copy when you need typed message IDs, translator comments, plural messages and the fallback chain.boilerplate/intl-format.ts: copy when you format numbers, money, dates, lists or relative time, or truncate or wrap text for canvas.boilerplate/pseudo-localize.ts: copy when you add the pseudo locale.references/text-layout.md: read when you lay out text for more than one language or script.references/process.md: read when you plan translation, a string freeze, LQA or culturalization.references/sources.md: read when you need the page behind a claim above.
Related skills
ui-ux-game(HUD, menus, subtitles and font-size options)character-design-narrative(character bibles and the dialogue-tree format whose lines become string-table entries)quest-mission-design(quest names, objective text)worldbuilding(world bible, factions and culture; the names and real-world parallels to review for culturalization)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

