# 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. 

## 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.