Adding New Languages to RetroArch¶

While translation is handled via the Crowdin¹ platform (more here), RetroArch's code must be adjusted for it to display new languages.

Files to change¶

Makefile.common
msg_hash.c
msg_hash.h
retroarch.c
griffin/griffin.c
intl/msg_hash_xx.c (new file)
intl/msg_hash_us.h
menu/menu_setting.c
libretro-common/include/libretro.h

Every new language must first be added to the project on Crowdin. This will ensure that a corresponding intl/msg_hash_xx.h file is created. Requests are accepted at the #retroarch-translations channel of the RetroArch Discord².

Main Instructions¶

To add a language with the English name XXXXX and two-letter code xx (be sure to use the same one as in the corresponding intl/msg_hash_xx.h file) follow these steps:

Open libretro-common/include/libretro.h.
1. Add a RETRO_LANGUAGE_XXXXX item to the retro_language enum just above RETRO_LANGUAGE_LAST, using the next available integer value.
  
  Do not rearrange the elements of this list! This would break the language association for the cores!
Open msg_hash.h.
1. Check if a MENU_ENUM_LABEL_VALUE_LANG_XXXXX item for your language is present in the msg_hash_enums enum; if not, add it.
2. Add declaration of a const char *msg_hash_to_str_xx(enum msg_hash_enums msg) function.
3. Add declaration of a int msg_hash_get_help_xx_enum(enum msg_hash_enums msg, char *s, size_t len) function.
Open msg_hash.c.
1. Add the following block inside the msg_hash_get_help_enum(enum msg_hash_enums msg, char *s, size_t len) function:
```
case RETRO_LANGUAGE_XXXXX:
   ret = msg_hash_get_help_xx_enum(msg, s, len);
   break;
```
2. Add the following block inside the get_user_language_iso639_1(bool limit) function:
```
case RETRO_LANGUAGE_XXXXX:
   return "xx";
```
3. Add the following block inside the msg_hash_to_str(enum msg_hash_enums msg) function:
```
case RETRO_LANGUAGE_XXXXX:
    ret = msg_hash_to_str_xx(msg);
    break;
```
Open Makefile.common.
1. Add intl/msg_hash_xx.o to OBJ.
Create a copy of intl/msg_hash_us.c and name it intl/msg_hash_xx.c.
Decide if intl/msg_hash_xx.c and intl/msg_hash_xx.h should use UTF-8 + BOM encoding. See the section below.
Open intl/msg_hash_xx.c.
1. Rename the msg_hash_get_help_us_enum() function to msg_hash_get_help_xx_enum().
2. Rename the menu_hash_to_str_us_label_enum() function to menu_hash_to_str_xx_label_enum().
3. Rename the msg_hash_to_str_us() function to msg_hash_to_str_xx() and, inside that same function:
4. Replace the call to menu_hash_to_str_us_label_enum() with a call to menu_hash_to_str_xx_label_enum().
5. Replace the #include "msg_hash_us.h" line with #include "msg_hash_xx.h".
Open intl/msg_hash_us.h.
1. Check if the following block is present, where Yyyyy is the native name of the language and if not, add it:
```
MSG_HASH(
   MENU_ENUM_LABEL_VALUE_LANG_XXXXX,
   "Xxxxx - Yyyyy"
   )
```
Open menu/menu_setting.c.
1. Add the following assignment to the setting_get_string_representation_uint_user_language() function:
```
modes[RETRO_LANGUAGE_XXXXX] = msg_hash_to_str(MENU_ENUM_LABEL_VALUE_LANG_XXXXX);
```
Open griffin/griffin.c.
1. Add the line #include "../intl/msg_hash_xx.c" below the existing, similar ones for other languages.
Open retroarch.c.
1. Add your language to enum retro_language rarch_get_language_from_iso(const char *iso639):
```
{"xx", RETRO_LANGUAGE_XXXXX},
```

Optional Adjustments¶

RGUI Compatibility¶

To make the new language usable with the RGUI menu driver:

Open menu/drivers/rgui.c.
Navigate to the rgui_fonts_init(rgui_t *rgui) function.
Add case RETRO_LANGUAGE_XXXXX: to
1. the extended ASCII section if the new language uses the Basic Latin/ASCII + Latin-1 Supplement range of UTF-8 or
2. any other present language the new language shares the alphabet with (like Russian).
If a new language was added, it is important to compile RetroArch with the changes and ensure the new language works correctly with RGUI.
If your language uses a different range of symbols, an RGUI compatible font must be added first. This is an extensive process, which is outside the scope of this article.

Enabling new languages in cores¶

Adding a language to RetroArch does not automatically enable it for the core options.
To do that for cores which have been added to Crowdin, follow these steps:

Locate the libretro.h file and add a RETRO_LANGUAGE_XXXXX item to the retro_language enum exactly the same as was done for RetroArch.
1. Alternatively, overwrite this file with the libretro-common/include/libretro.h file from RetroArch's code.
Locate the libretro_core_options.h file and open it.
1. Add &options_xx, at the end of the retro_core_options_v2 struct. Remember to keep the same order as in the retro_language enum.

Adding cores to Crowdin is a whole other elaborate process and, currently, can only be performed by a Crowdin manager. Suggestions/Requests can be submitted on Discord to DisasterMo#0389.

Encoding of translation files¶

Translation files (intl/msg_hash_xx.{c,h}) in general must be UTF-8 encoded.
For some languages, these files need to have a "UTF-8 Unicode (with BOM)" encoding. This can be done using the 'Encoding' option of editors like Notepad++ and Notepadqq. AFAIK, this is because of a requirement of the MSVC compilers for the Windows platform. Examples of this as of now are:

msg_hash_ar.{c,h}
msg_hash_chs.{c,h}
msg_hash_cht.{c,h}
msg_hash_ja.{c,h}
msg_hash_ko.{c,h}
msg_hash_pl.{c,h}
msg_hash_ru.{c,h}
msg_hash_vn.h

Be careful when creating and editing your new translation files, as some text editors do strip the BOM without warning.

Examples¶

Adding languages to RetroArch¶

Arabic:
Indonesian, Swedish and Ukrainian (+RGUI):
- Add Indonesian, Swedish and Ukrainian language options

Enabling new languages for cores¶

mgba:
- Enable Indonesian, Swedish and Ukrainian localisations

Translation¶

If you speak the target language xx then you could start translating on Crowdin.
Instructions and recommended reading for that can be found here.

Please do not change the intl/msg_hash_xx.h files directly!

The intl/msg_hash_xx.c files are not yet included on Crowdin, but that's because an overhaul of these files is currently a work-in-progress. If you just can't wait any longer, you can start translating those files by replacing the English texts with the respective translations.
We will try to preserve your efforts.