Skip to content

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.

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 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 message of 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.
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).

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.
  • 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 with Intl.DateTimeFormat in 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 Intl API 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.

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.

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.
  • 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 (locales in packages/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.