mirror of
https://github.com/libretro/docs.git
synced 2026-11-07 11:06:09 -10:00
Merge pull request #1039 from DisasterMo/master
Add instructions on how to set up translations for libretro cores
This commit is contained in:
3 files changed
+114
-17
No files matched your search
@@ -0,0 +1,113 @@
|
||||
# Adding Translations
|
||||
|
||||
## Setting up translation with Crowdin
|
||||
|
||||
The scripts and workflows referenced here, as well as some sample `core_options` files, can be found in the [RetroArch translation example](https://github.com/libretro/RetroArch/tree/master/libretro-common/samples/core_options/example_translation).
|
||||
|
||||
### Requirements
|
||||
|
||||
Make sure the core is libretro conformant:
|
||||
both `libretro_core_options.h`, containing the English texts, and
|
||||
`libretro_core_options_intl.h`, containing all already existing
|
||||
translations, if any, must be present in the same directory.
|
||||
|
||||
> Please note: `libretro_core_options_intl.h` does not need to contain
|
||||
anything, if no translations exist or none of them should be preserved.
|
||||
|
||||
The scripts are not compatible with text filled in by macros or during run time.
|
||||
The procedure should not fail - but those texts will not be made translatable.
|
||||
|
||||
Also, please verify the existence and correct use of
|
||||
|
||||
`#ifdef HAVE_LANGEXTRA`
|
||||
|
||||
and/or
|
||||
|
||||
`#ifndef HAVE_NO_LANGEXTRA`
|
||||
|
||||
pre-compiler instructions in `libretro_core_options.h` to remove any
|
||||
references to additional languages on platforms which cannot handle them,
|
||||
e.g. due to limited RAM.
|
||||
For an example, refer to an up-to-date core, like [gambatte-libretro](https://github.com/libretro/gambatte-libretro/blob/master/libgambatte/libretro/libretro_core_options.h).
|
||||
|
||||
> Make sure `options_intl` in `libretro_core_options.h` correctly references the `_intl` options, or the translations will not be applied!
|
||||
|
||||
### Adding automatic Crowdin sync
|
||||
|
||||
Place the `intl` and `.github` folders from the [sample folder](https://github.com/libretro/RetroArch/tree/master/libretro-common/samples/core_options/example_translation), including content, into the root
|
||||
of the repository.
|
||||
|
||||
In `.github/workflows` are two files: `crowdin_prep.yml` & `crowdin_translate.yml`.
|
||||
|
||||
In each of those are placeholders, which need to be replaced.
|
||||
|
||||
For convenience, one can run `intl/activate.py`, which will try to find
|
||||
the `libretro_core_options.h` file as well as identify the core name to
|
||||
fill those placeholders with.
|
||||
|
||||
Even then, one should still check if it produced the correct result:
|
||||
|
||||
For `crowdin_prep.yml`:
|
||||
> **NOTE:** Please verify, that this workflow watches the correct branch (e.g. main, instead of master)!
|
||||
Uploads happen, whenever `libretro_core_options.h` of that branch is changed.
|
||||
|
||||
- <PATH/TO/libretro_core_options.h FILE> (x2)
|
||||
- replace with the full path from the root of the repo to the
|
||||
`libretro_core_options.h` file
|
||||
|
||||
- <CORE_NAME>
|
||||
- the name of the core (or repo)
|
||||
|
||||
And for crowdin_translate.yml:
|
||||
- <0-59> <0-23>
|
||||
- Minute and hour at which the sync will happen.
|
||||
The script will generate a random time for this, to avoid
|
||||
stressing GitHub & Crowdin with many simultaneous runs.
|
||||
|
||||
- <CORE_NAME>
|
||||
- same as above
|
||||
|
||||
- <PATH/TO/libretro_core_options_intl.h FILE> (x2)
|
||||
- replace with the full path from the root of the repo to the
|
||||
'libretro_core_options_intl.h' file
|
||||
|
||||
Create a Pull Request and ask a Crowdin project manager, either on [Crowdin](https://crowdin.com/project/retroarch) or, preferably, on [Discord](https://ra-link.web.app/discord) in the `retroarch-translations` channel, to provide you with an access token. Create an Actions repository secret on GitHub named CROWDIN_API_KEY for this access token.
|
||||
|
||||
<!-- TODO: set correct permissions https://github.com/marketplace/actions/github-push -->
|
||||
When everything is ready, run the "Crowdin Translations Initial Setup" workflow manually to upload the source texts and any translations to Crowdin.
|
||||
|
||||
> You may either disable the initial workflow or even remove it from your repository. Running it more than once is very much discouraged! That may mess with the newest translations, which are usually not yet incorporated into the repository.
|
||||
|
||||
Finally, it is recommended to run the "Crowdin Translation Sync" workflow manually once. If a "Permission to \<repository> denied" error occurs, you might need to configure the GITHUB_TOKEN with the appropriate access rights, [see here](https://github.com/marketplace/actions/github-push#requirements-and-prerequisites).
|
||||
|
||||
### (For Crowdin project managers) Creating an access token
|
||||
|
||||
To create an access token, navigate to the account settings via your profile picture in the top right. Change to the API tab. Here you should find a `New Token` button.
|
||||
|
||||
Name the token after the core/repository, which will receive it. The following permissions should be set:
|
||||
|
||||
- Projects
|
||||
- read
|
||||
- Source files & strings
|
||||
- read & write
|
||||
- Translations
|
||||
- read & write
|
||||
- (optional) Translation status
|
||||
- read
|
||||
|
||||
> Please provide these access tokens to the core developers in a private message and delete those after successful setup. Do not share tokens publicly or store them in plain text long term!
|
||||
|
||||
## 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:
|
||||
|
||||
1. 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.
|
||||
- Alternatively, overwrite this file with the `libretro-common/include/libretro.h` file from RetroArch's code.
|
||||
2. Locate the `libretro_core_options.h` file and open it.
|
||||
- Add `&options_xx,` at the end of the `options_intl` struct. Remember to keep the same order as in the `retro_language` enum.
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
- mgba:
|
||||
- [Enable Indonesian, Swedish and Ukrainian localisations](https://github.com/libretro/mgba/commit/b0cdccc9ad2e5a8cd40ad4b9a3db1587d6f1560b)
|
||||
@@ -174,18 +174,6 @@ To make the new language usable with the RGUI menu driver:
|
||||
4. If a new language was added, it is important to compile RetroArch with the changes and ensure the new language works correctly with RGUI.
|
||||
5. 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:
|
||||
|
||||
1. 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.
|
||||
2. 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.
|
||||
|
||||
### Narrator support
|
||||
|
||||
1. For Mac. (compatible with **say**)
|
||||
@@ -240,11 +228,6 @@ Be careful when creating and editing your new translation files, as some text ed
|
||||
|
||||
* [List of merges related to adding languages](https://github.com/libretro/RetroArch/pulls?q=is%3Apr+is%3Amerged+in%3Atitle+add+language+option+)
|
||||
|
||||
### Enabling new languages for cores
|
||||
|
||||
* mgba:
|
||||
* [Enable Indonesian, Swedish and Ukrainian localisations](https://github.com/libretro/mgba/commit/b0cdccc9ad2e5a8cd40ad4b9a3db1587d6f1560b)
|
||||
|
||||
## Translation
|
||||
|
||||
If you speak the target language `xx` then you could start translating on Crowdin.
|
||||
|
||||
@@ -416,6 +416,7 @@ nav:
|
||||
- 'Core Development Overview': 'development/cores/developing-cores.md'
|
||||
- 'Dynamic Rate Control for Emulators': 'development/cores/dynamic-rate-control.md'
|
||||
- 'OpenGL Accelerated Cores': 'development/cores/opengl-cores.md'
|
||||
- 'Core Options Translation': 'development/cores/core-options-translation.md'
|
||||
- 'Core-Specific Docs':
|
||||
- 'Nintendo - GameCube/Wii (Dolphin)': 'development/cores/core-specific/dolphin.md'
|
||||
- 'Nintendo - GameCube/Wii (Ishiiruka)': 'development/cores/core-specific/ishiiruka.md'
|
||||
|
||||
Reference in new issue
Block a user