Localization
How the desktop app is translated, how to improve a translation, and how to localize strings in code and plugins.
The desktop app’s menus, messages and buttons load from language files. There are about 100 languages in apps/desktop/lang/, many of them first produced with machine translation, so corrections from people who use the app in their language are welcome.
Translation files
Each file in apps/desktop/lang/ is named by its language tag (de.json, pt-BR.json) and holds a JSON object mapping the English string to the translation:
{
"%@ of %@": "%1$@ de %2$@",
"Accept": "Aceptar",
"Account": "Cuenta",
"Moved to %@": "Movido a %@"
}
%@ is a placeholder for text filled in at runtime, such as a folder name. When a string has several placeholders, the translation can refer to them by position with %1$@, %2$@, so you can reorder them for your language’s word order.
A missing translation falls back to English.
Improving a translation
- Edit the file for your language in
apps/desktop/lang/, on GitHub or in a clone. - To find strings your language is missing, run from
apps/desktop:It compares your locale withnode scripts/improve-localization.jsen.jsonand either prompts you for each missing string (leave it blank to skip) or writesnullfor every missing key so you can fill them in the file. - Open a pull request (see Contributing).
Running in a specific language
The language is set in Preferences > General and read at launch, so relaunch to apply it. Left on automatic, the --lang flag picks one:
/Applications/Airpost.app/Contents/MacOS/Airpost --lang=de # installed app on macOS
npm start -- --lang=de # from apps/desktop
Arabic, Persian, Hebrew and Kurdish run right to left: the workspace gets dir="rtl" and the app’s stylesheets are mirrored. The UI kit uses logical CSS properties instead, so it isn’t mirrored a second time.
Localizing code
Wrap user-facing strings in localized(). Plugins import it from mailspring-exports.
import { localized, localizedReactFragment, isRTL } from 'mailspring-exports';
localized('Archive');
localized('Moved to %@', folder.displayName);
localized('%1$@ of %2$@', current, total);
localizedReactFragment does the same with React nodes as substitutions, and isRTL tells you whether the current language runs right to left.
After adding or removing strings in the app, run from apps/desktop:
node scripts/format-localizations.js
It finds every localized() call in the source, adds new strings to en.json, removes unused strings from every locale, and sorts the files.
Third-party plugins can call localized(), but their strings are only translated if the same English string is already in the app’s language files.