Translate a game

Follow these steps in order to show a game in another language. Each step ends on a condition you can check. Finish the condition before you start the next step.

Translations is the reference these steps use: catalogs, messages, which locale a player sees, and the checks and their codes. Translate each locale yourself: Boardweaver translates nothing for you.

1. Read the game's text

Call get_game for the game's defaultLocale and its translations. Call list_files for /src/i18n/, /src/rules/ and /src/marketing/. Read the default catalog with read_file.

Done when you know the default locale, each locale the game already has, and the locale the author wants added.

2. Move every word into the default catalog

A word in the code cannot be translated. Find each one and move it into the default catalog:

• In the client, every word in JSX, in an attribute such as aria-label or title, or in a string the client shows. Show it with react-intl by its key (Text in the player's language).
• In the game logic, every log line, offer label and refusal reason already is a message. Check that no message passes finished words as a text value, which no catalog can translate (Log lines).
• Format numbers, dates and lists with react-intl, so they follow the language.

Then start a session with start_game and locale: "en-XA", and call render_game with format: "image" for each seat. Any text that shows with no accents and no brackets is still in the code, apart from what a render always keeps in English (Checking a locale).

Done when a render in en-XA shows no plain English other than what a render always keeps in English, and validate_code answers valid: true.

3. Write the locale's catalog

Write /src/i18n/<locale>.json with write_file. Give it every key of the default catalog, each message translated. Keep each message's placeholders, tags and select keys, and keep {player} where the default message has it. Write a plural with the categories of the new language, such as only other for Japanese and Chinese.

Done when validate_code answers valid: true and lists no missing or extra message for the locale.

4. Translate the name and description

Call update_game with translations, holding every locale the game has: the ones get_game answered and the new one, each with its name and description.

Done when validate_code names no locale whose name or description has no translation.

5. Translate the pages

Write each rules page again in /src/rules/<locale>/, with the same slug and the same links, and the marketing page in /src/marketing/<locale>/index.bwss (Write the rules pages, Write the marketing page). Keep the same image keys, or upload images with the locale's text under their own keys.

Done when each page in /src/rules/ and /src/marketing/ has a copy in the locale's folder, and validate_code answers valid: true.

6. Render in the locale and in en-XA

Start a session with start_game and the new locale. Call render_game with format: "image" for each seat, at a desktop and at a phone viewport, in light and dark. Play a few decisions with apply_action, and render again after them. Then render the same positions with locale: "en-XA".

Read each committed decision's lines in apply_action's answer: check that each text reads as a sentence, and that each line's message.key is a key of the new catalog. A line's text is always in the default locale, so read the translated lines in the render in the locale.

Done when you have a render of each seat in the locale and in en-XA, at both viewports, and a list of every place where text is clipped, overlaps, leaves its box, or shows boxes in place of characters.

7. Fix overflow and missing glyphs

Fix each place on the list:

• Let text wrap, or give its box room to grow, rather than fixing its width. Use CSS logical properties, such as margin-inline-start, so the layout follows the language's direction.
• Shorten a translation only when the box cannot grow, and keep its meaning.
• Load a font from Google Fonts that has the language's glyphs when a render shows boxes in place of characters (The React client). List it in fontFamily after the font the client uses now, so it draws only the glyphs that font lacks.

Start a new session after each change, since a session keeps the client and catalogs it started with.

Done when a render of each seat, in the locale and in en-XA, at both viewports, shows every text whole and readable.

8. Commit

Call commit.

Done when commit succeeds and its catalogCoverage lists nothing for the new locale.