# Internationalization

## File and data structure

### Display language
Currently all the wording used in MuditaOS interface is collected in the form of JSON files which are located in [the image/assets/lang folder](../image/assets/lang/).

The default fallback file for every language is currently the English version - `English.json`.

Language file naming pattern should be universal because MuditaOS displays languages based on the file name (without extension) eg. `Deutsch.json` will be displayed in language settings as `Deutsch`.

The name of a language file should also be in the language of the created file eg. for English it should be `English.json`, for Polish `Polski.json` etc.

The structure of the file is typical for JSON files:
```c++
(...)
"common_open": "OPEN",
"common_call": "CALL",
"common_save": "SAVE",
"common_send": "SEND",
(...)
```
The keys on the left side refer to the values on the right side. These values are later displayed in MuditaOS applications.

### Keyboard input language

Keyboard input language files have JSON extension and are located in [the image/assets/profiles folder](../image/assets/profiles/).

Every language has its own files for upper and lower letters. Here's an example of a working JSON file for `English_lower.json`:
```c++
{
  "filetype": "normal",
  "31": ".,_:;)(?!#/*+",
  "32": "abc",
  "33": "def",
  "41": "ghi",
  "42": "jkl",
  "43": "mno",
  "51": "pqrs",
  "52": "tuv",
  "53": "wxyz",
  "61": "0x0A",
  "62": " ",
  "63": "0x08"
}
```
The first value declares the type of this file:
- `normal` - they are shown in input language settings, user can change it through GUI (e.g. from English to Polish).
- `special` - they won't show in input language settings, they can be modified only in code (e.g. numeric keyboard).

Normal-type files will be displayed in settings by their filename (e.g. `English_lower.json` and `English_upper.json` will be shown as `English`). When you add a new input language you should always include files for lower and upper letters for it.

Next key-value pairs includes code of the key (key) and characters available under this key (value). However, there are two buttons with hexadecimal number (under `61` and `63` buttons). Their value tells MuditaOS what they do:
- `0x0A` - after shortpress (explained below) button change input mode (from lower letters to upper, from upper to numbers etc.). After longpress they show special characters window.
- `0x08` - after shortpress button deletes character.

Files naming pattern should be: `<language>_<lower/upper>`, eg. correct implementation of Rodian input language should consist of two files: `Rodian_lower.json` and `Rodian_upper.json`.

We also distinguish two types of button presses:
- `shortpress` - they are used to write letters taken from loaded input language file.
- `longpress` - this type of button press is used, when user keeps button pressed for at least 2 seconds and then releases. In text it is used to write numbers.

Example: If you are using English keyboard language for lower letters and press `1` button (keycode `31`) and quickly release it, then in SMS textbox `a` letter will appear. But if you hold this button pressed for at least 2 seconds and then release it, `1` number will appear.

Definition for every key code used in the phone is in [the key_codes.hpp file (KeyCodes enum)](../module-bsp/bsp/keyboard/key_codes.hpp)

### Date and time

MuditaOS follows [Linux `date`](https://man7.org/linux/man-pages/man1/date.1.html) to format date and time.

## Font conversion

MuditaOS doesn't have built-in support for ttf/otf fonts, so we generate bitmap files for fonts. The official release uses GT Pressura Typeface which is a licensed font ([more info](../LICENSE.md))

MuditaOS supports the following languages (and characters) out-of-the-box:

- English
- German 
- Spanish 
- Polish
- French

For other languages there might be a need to add language-specific glyphs, build them using [fontbuilder](https://github.com/mudita/fontbuilder) and add them to the repository.

[Here's a list of glyphs that are supported by GT Pressura](https://www.grillitype.com/api/storage/app/uploads/public/5b6/c52/16b/5b6c5216b40a8675629257.pdf) (our current license covers only the Latin alphapbet characters).

[Here's a list of characters currently added to the build](https://github.com/mudita/fontbuilder/blob/master/charset.txt).

If your characters aren't currently supported by the main font or the defualt fallback font (DeJavu Sans Bold) please know that we're working on adding a feature inside MuditaOS that would enable to render the UI in more languages with a font provided by the user.

### Adding glyphs

We use [fontbuilder](https://github.com/mudita/fontbuilder). It has font sets saved in files. This is not the best solution to store system presets (we should rather have it in release process). In order to do this:

- feed FontBuilder headless run with preset file and build MPF (Mudita Pure Font)
- put these fonts in build folder

On Mudita Pure phone we use:

- default font (`gt_pressura` font family)
- default fallback font (DeJavu Sans Bold size 27 **Emojis only**)

The `▯` glyph indicates that there is no glyph for a unicode character in the current font.

#### Naming convention

It’s a good practice not to rename font names - these are stored in font metadata too and metadata is used in code (**not the font file name**). Please just keep names as they are.

#### Where are the files?

- Source font files used for the build: `PurePhone/image/assets/fonts/`
- Font files used at runtime (copied upon build): `PurePhone/<build_folder>/assets/fonts/`

## How to start localizing the interface

1. Create an issue with the localization you want to start working on. Please use the following issue title scheme: `[Language] localization [emoji_flag]` eg. `Polish localization 🇵🇱`. The emoji flag is a small detail that can help other community members in finding the localization they're interested in and helping you out in implementing it. Please make sure that the localization you want to implement has not been already implemented.
2. Add a `i18n` label to your new issue on GitHub.
3. Follow [the "Contributing to MuditaOS" article](../CONTRIBUTING.md).
4. As soon as you create a Pull Request with your localization we will review it and add it to the official MuditaOS distribution.