Internationalization
This page explains how the product speaks two languages, where each text lives and how much of it is translated today. It is part of section 9 of the arc42 template.
The problem
Section titled “The problem”Ochema is built for the United States, where a large share of drivers and office staff read Spanish. A recruiter may work in English while the applicant reads Spanish, in the same conversation. The language is therefore a property of the person who reads, not of the company, and a text that is missing in Spanish must never leave a blank on screen.
The rule
Section titled “The rule”- The product has two languages, English (
en) and Spanish (es). English is the source and the fallback. - No screen writes a text directly. Every text comes from a dictionary, by key.
- The API speaks in codes, not sentences. A screen translates the code; the English
messageof the API is a fallback for logs and developers. - A text sent to a person outside the company (a page, an SMS, an email) uses the language of that person when it is known.
How the code applies it
Section titled “How the code applies it”Whose language applies
Section titled “Whose language applies”| Reader | Where the language comes from |
|---|---|
| A user of the office system | The account menu, items “English” and “Español”. The choice is saved with PATCH /auth/me and follows the user to any browser. Stored in users.locale. |
| A visitor of the careers site | ?lang= in the address wins; without it, the first language of the browser’s Accept-Language that the site has (es-MX counts as Spanish); otherwise English. A language switch on the page writes ?lang=. Not stored: see apps/careers/src/i18n/index.ts. |
| A candidate | The language of the form the candidate applied in, or the preferredLocale field of the lead intake API. Stored in candidates.preferred_locale. |
| A candidate filling the full application | The language of the candidate, changed on the page if the candidate switches. Stored in driver_applications.locale. |
The database accepts only the two values: every language column has a check constraint built by localeCheck (packages/db/src/schema/helpers.ts).
Where each text lives
Section titled “Where each text lives”| Text | Where | How Spanish works |
|---|---|---|
| Screens of the office system | apps/web/src/i18n (shared texts) and one texts.en.ts and texts.es.ts per module under apps/web/src/routes/<module> |
i18next, created by createI18n in packages/app-kit/src/i18n.ts. The Spanish dictionary has exactly the English keys; an entry left empty shows the English text. |
| Screens of the driver app | apps/driver/src/i18n |
The same mechanism. |
| Careers page, job page and application form | apps/careers/src/i18n/en.ts and es.ts |
Rendered on the server in the language of the visitor. The type of the Spanish dictionary is the type of the English one. |
| Scheduling, full application, signing, candidate area, unsubscribe and employer response pages | A _texts.ts file next to each page in apps/careers/src/pages |
Both languages in the same file, with the same type. |
| Message templates of a company | message_templates.body_en and body_es (and the subjects) |
MessageSendService picks the Spanish text for a candidate whose language is Spanish and falls back to English when it is empty (apps/api/src/modules/platform-messaging/message-send.service.ts). |
| Offer and contract templates | body_en and body_es of offer_templates and contract_templates |
Written by the company in each language it uses. |
| Consent texts, legal texts and system SMS replies | The catalogs consent_texts, legal_texts and system_message_texts, one row per key, language and version |
A new wording is a new version written by a migration, never an edit, so a recorded consent always points to the exact text the person saw. |
| Errors of the API | errors.<code> in the dictionaries of each app |
The API returns a stable code; the screen translates it. See Error handling. |
Dates, numbers and places
Section titled “Dates, numbers and places”- Time zone. Every instant is stored as
timestamptz. A company and a user each have a time zone (tenants.timezone,users.timezone), and screens format dates withIntl.DateTimeFormatin the language and the time zone of the user (apps/web/src/lib/format.ts). The allowed hours of an SMS are counted in the time zone of the candidate. See Messaging. - Formats. Dates and numbers are formatted by the
IntlAPI of the platform for the user’s language. The repository depends on no date library. - United States conventions. Phone numbers are stored in E.164 with the United States as the default region, addresses use the list of states, and money is stored as whole cents.
How much is translated today
Section titled “How much is translated today”Counted in the dictionaries of the code and, for the default templates, in a database with every migration applied. A text counts when its Spanish entry is not empty.
| Surface | English texts | With a Spanish text | Spanish |
|---|---|---|---|
Careers site: careers page, job page and application form (apps/careers/src/i18n) |
155 | 155 | Complete |
Careers site: the six other public pages (_texts.ts) |
6 files | 6 files, each with both languages under one type, so a missing text does not compile | Complete |
Default message templates (message_template_defaults) |
30 | 30 | Complete |
Office system (apps/web) |
7,084 | 550, of which 540 in Attract and Recruit | Partial |
Driver app (apps/driver) |
138 | 1 | Not translated yet |
A user who chooses “Español” in the office system today sees Spanish where it exists and English everywhere else. The pages an applicant or a driver sees are complete in both languages.
What guarantees it
Section titled “What guarantees it”| Guarantee | Enforced by |
|---|---|
| Spanish never has a key English lacks, or the other way round. | The type Dictionary (apps/web/src/i18n/en.ts) and apps/web/test/i18n.test.ts, which compares the two sets of keys. The same test exists for the driver app in apps/driver/test/i18n.test.ts. |
| No English text is empty, and every key a screen uses exists. | apps/web/test/i18n.test.ts reads the source of every screen and checks each literal key. |
| Every error code and every permission of the API has a text. | The same test reads the codes and the permission keys from packages/contracts/openapi.json. |
| A misspelled key does not compile. | apps/web/src/i18n/i18next.d.ts types the keys of t() from the English dictionary. |
| An empty Spanish entry falls back to English. | packages/app-kit/test/i18n.test.ts. |
| The public pages have every text in both languages and open in the right one. | apps/careers/test/pages.test.ts, apply.test.ts, schedule.test.ts and full-application.test.ts. |
| Choosing a language saves it on the user and applies it. | apps/web/test/account-language.test.tsx. |
Known limits
Section titled “Known limits”- Spanish in the office system is partial, as the table above shows. The mechanism is complete; the translation is not.
- Two languages, fixed. The list is in the code (
localesinpackages/app-kit/src/i18n.ts) and in the check constraints of the database. A third language is a change to both. - Some messages of the API are shown as written. A few validation messages are written for one specific case and marked
specific; the screen shows them as they come, in English. - The landing site and this documentation are in English only.
- What a company writes is not translated. Job descriptions, templates and custom document types appear in the language the company wrote them in. For templates the company fills both languages itself.
Related
Section titled “Related”- Design system: where the appearance of the screens lives.
- Messaging: how the language and the local time of a candidate are used when a message is sent.
- Risks and known limitations: the state of Spanish from the point of view of a customer.