W10: Two Languages: English and Japanese

A museum that welcomes visitors from many countries does not paint its signs in one language and repaint them later. Each sign has a number, and there is a booklet for each language: sign 12 in the English booklet says "Ancient pottery", in the Japanese booklet "古代の陶器". Adding a language means writing one more booklet, not repainting the museum. Your app works like that from day one. Each piece of text has a key, and there is one dictionary file per language.

Why From the Start

Adding a second language to a finished app is painful: the words are scattered through every page, glued into the HTML. Many people this course is for read Japanese more comfortably than English, and many of their users do too. So in the stack, every visible word goes through one function, t("key"), from the very first page. A Japanese app costs almost nothing extra.

The Two Dictionaries

The words live in messages/en.json and messages/ja.json. Same keys, different words:

{
 "app.name": "Notes",
 "notes.add": "Add Note",
 "error.title_empty": "Write something first."
}
{
 "app.name": "メモ",
 "notes.add": "メモを追加",
 "error.title_empty": "何か書いてください。"
}

Keys are written like area.thing: notes.add, error.title_empty. They say where the word is used, so you can find it later.

t() in a Template

In every template, t is ready to use:

<button class="btn">{{ t("notes.add") }}</button>

An English visitor sees "Add Note"; a Japanese visitor sees "メモを追加". The template is the same file.

Words can have blanks too. If a message is "Hello, {name}", the template writes {{ t("greeting", name=user) }}. In Japanese the blank can sit wherever Japanese grammar wants it: "{name}さん、こんにちは". That is why you never build sentences by gluing pieces together in the code: the order of words changes between languages.

How the Language Is Chosen

In app/i18n.py, the function choose decides, in this order:

  1. The person's choice. The 日本語 and English buttons at the top post to /language, which saves a cookie called lang for a year and reloads the page.
  2. The browser's language. If there is no cookie, the app reads the Accept-Language header the browser sends, and takes the first language it knows.
  3. English, if nothing else matches.

The person's choice always wins over the browser. The starter has a test for exactly that, in tests/test_app.py: a browser that prefers Japanese, but a person who clicked English, gets English.

If a key is missing in Japanese, translate falls back to the English text, then to the key itself. The page never breaks, but a missing word shows up in English, which is a bug to fix.

The Test That Keeps Both in Step

tests/test_i18n.py checks two things every time the tests run:

So if Pi adds a button with t("notes.edit") but forgets ja.json, the tests fail. This is the harness's Red and Green working for languages too (W03). Pi Workbench will do this step for you soon: a check after every edit that also finds visible text written straight into a template, without t().

Adding a Word

Three steps, always together:

  1. Use the key in the template: {{ t("notes.edit") }}.
  2. Add it to messages/en.json: "notes.edit": "Edit".
  3. Add it to messages/ja.json: "notes.edit": "編集".

When you ask Pi for a change with new words, say so, and give the Japanese if you know it:

"Add an Edit button next to Delete. In Japanese it says 編集."

If you do not know the Japanese, Pi will write some. Machine translation is fine for a first version; ask a Japanese speaker to read it before you ship. The same goes for error messages: they are words too, so the logic returns a key (like error.title_empty, see W09) and the page translates it.

Small Things That Matter

The Rest of This School

This site is in English, Japanese and Portuguese, and it is built the same way: the English is the source, and the other languages sit beside it. T40 tells the story of a real English and Japanese site, including how to break Japanese lines nicely.

This Week's Exercise

  1. Open both message files side by side. Find each key in the templates.
  2. Click 日本語 in your app, then clear the site's cookies and set your browser to prefer Japanese. Does the app still open in Japanese?
  3. Ask Pi for the Edit button with its Japanese word. Check all three places changed.
  4. Remove one key from ja.json by hand and run uv run pytest. Read the failure, then put the key back.

Key Takeaways

  • Every visible word goes through t("key"); the words live in messages/en.json and messages/ja.json with the same keys
  • The language comes from the person's choice (a cookie), else the browser's Accept-Language, else English
  • Never glue sentences together in code: use blanks like {name}, because word order changes between languages
  • test_i18n.py fails when a language misses a key or a template uses an unknown key
  • A new word means three changes together: the template, en.json and ja.json