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:
- The person's choice. The 日本語 and English buttons at the top post to
/language, which saves a cookie calledlangfor a year and reloads the page. - The browser's language. If there is no cookie, the app reads the
Accept-Languageheader the browser sends, and takes the first language it knows. - 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:
- Every language file has exactly the same keys.
- Every
t("...")key used in a template exists in English.
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:
- Use the key in the template:
{{ t("notes.edit") }}. - Add it to
messages/en.json:"notes.edit": "Edit". - 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
<html lang="...">inbase.htmlis set to the chosen language, so screen readers and browsers pronounce and format correctly.- Japanese text has no spaces between words, so long lines wrap differently. Check your pages in Japanese at phone width.
- Dates are written differently too (15 Oct 2026 or 2026年10月15日): ask Pi to format them per language.
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
- Open both message files side by side. Find each key in the templates.
- Click 日本語 in your app, then clear the site's cookies and set your browser to prefer Japanese. Does the app still open in Japanese?
- Ask Pi for the Edit button with its Japanese word. Check all three places changed.
- Remove one key from
ja.jsonby hand and runuv 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