Skip to content

Commit 4d8b20d

Browse files
fpscanfpscan
authored
Merge pull request #1039 from DisasterMo/master
Add instructions on how to set up translations for libretro cores
2 parents 137b5d2 + 1ad01a5 commit 4d8b20d

File tree

3 files changed

+114
-17
lines changed

3 files changed

+114
-17
lines changed

‎docs/development/cores/core-options-translation.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Adding Translations
2+
3+
## Setting up translation with Crowdin
4+
5+
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).
6+
7+
### Requirements
8+
9+
Make sure the core is libretro conformant:
10+
both `libretro_core_options.h`, containing the English texts, and
11+
`libretro_core_options_intl.h`, containing all already existing
12+
translations, if any, must be present in the same directory.
13+
14+
> Please note: `libretro_core_options_intl.h` does not need to contain
15+
anything, if no translations exist or none of them should be preserved.
16+
17+
The scripts are not compatible with text filled in by macros or during run time.
18+
The procedure should not fail - but those texts will not be made translatable.
19+
20+
Also, please verify the existence and correct use of
21+
22+
`#ifdef HAVE_LANGEXTRA`
23+
24+
and/or
25+
26+
`#ifndef HAVE_NO_LANGEXTRA`
27+
28+
pre-compiler instructions in `libretro_core_options.h` to remove any
29+
references to additional languages on platforms which cannot handle them,
30+
e.g. due to limited RAM.
31+
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).
32+
33+
> Make sure `options_intl` in `libretro_core_options.h` correctly references the `_intl` options, or the translations will not be applied!
34+
35+
### Adding automatic Crowdin sync
36+
37+
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
38+
of the repository.
39+
40+
In `.github/workflows` are two files: `crowdin_prep.yml` & `crowdin_translate.yml`.
41+
42+
In each of those are placeholders, which need to be replaced.
43+
44+
For convenience, one can run `intl/activate.py`, which will try to find
45+
the `libretro_core_options.h` file as well as identify the core name to
46+
fill those placeholders with.
47+
48+
Even then, one should still check if it produced the correct result:
49+
50+
For `crowdin_prep.yml`:
51+
> **NOTE:** Please verify, that this workflow watches the correct branch (e.g. main, instead of master)!
52+
Uploads happen, whenever `libretro_core_options.h` of that branch is changed.
53+
54+
- <PATH/TO/libretro_core_options.h FILE> (x2)
55+
- replace with the full path from the root of the repo to the
56+
`libretro_core_options.h` file
57+
58+
- <CORE_NAME>
59+
- the name of the core (or repo)
60+
61+
And for crowdin_translate.yml:
62+
- <0-59> <0-23>
63+
- Minute and hour at which the sync will happen.
64+
The script will generate a random time for this, to avoid
65+
stressing GitHub & Crowdin with many simultaneous runs.
66+
67+
- <CORE_NAME>
68+
- same as above
69+
70+
- <PATH/TO/libretro_core_options_intl.h FILE> (x2)
71+
- replace with the full path from the root of the repo to the
72+
'libretro_core_options_intl.h' file
73+
74+
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.
75+
76+
<!-- TODO: set correct permissions https://github.com/marketplace/actions/github-push -->
77+
When everything is ready, run the "Crowdin Translations Initial Setup" workflow manually to upload the source texts and any translations to Crowdin.
78+
79+
> 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.
80+
81+
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).
82+
83+
### (For Crowdin project managers) Creating an access token
84+
85+
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.
86+
87+
Name the token after the core/repository, which will receive it. The following permissions should be set:
88+
89+
- Projects
90+
- read
91+
- Source files & strings
92+
- read & write
93+
- Translations
94+
- read & write
95+
- (optional) Translation status
96+
- read
97+
98+
> 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!
99+
100+
## Enabling new languages in cores
101+
102+
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:
103+
104+
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.
105+
- Alternatively, overwrite this file with the `libretro-common/include/libretro.h` file from RetroArch's code.
106+
2. Locate the `libretro_core_options.h` file and open it.
107+
- Add `&options_xx,` at the end of the `options_intl` struct. Remember to keep the same order as in the `retro_language` enum.
108+
109+
110+
### Example
111+
112+
- mgba:
113+
- [Enable Indonesian, Swedish and Ukrainian localisations](https://github.com/libretro/mgba/commit/b0cdccc9ad2e5a8cd40ad4b9a3db1587d6f1560b)

‎docs/development/retroarch/new-translations.md‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -174,18 +174,6 @@ To make the new language usable with the RGUI menu driver:
174174
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.
175175
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.
176176

177-
### Enabling new languages in cores
178-
179-
Adding a language to RetroArch does not automatically enable it for the core options.
180-
To do that for cores which have been added to Crowdin, follow these steps:
181-
182-
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.
183-
1. Alternatively, overwrite this file with the `libretro-common/include/libretro.h` file from RetroArch's code.
184-
2. Locate the `libretro_core_options.h` file and open it.
185-
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.
186-
187-
> 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.
188-
189177
### Narrator support
190178

191179
1. For Mac. (compatible with **say**)
@@ -240,11 +228,6 @@ Be careful when creating and editing your new translation files, as some text ed
240228

241229
* [List of merges related to adding languages](https://github.com/libretro/RetroArch/pulls?q=is%3Apr+is%3Amerged+in%3Atitle+add+language+option+)
242230

243-
### Enabling new languages for cores
244-
245-
* mgba:
246-
* [Enable Indonesian, Swedish and Ukrainian localisations](https://github.com/libretro/mgba/commit/b0cdccc9ad2e5a8cd40ad4b9a3db1587d6f1560b)
247-
248231
## Translation
249232

250233
If you speak the target language `xx` then you could start translating on Crowdin.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -416,6 +416,7 @@ nav:
416416
- 'Core Development Overview': 'development/cores/developing-cores.md'
417417
- 'Dynamic Rate Control for Emulators': 'development/cores/dynamic-rate-control.md'
418418
- 'OpenGL Accelerated Cores': 'development/cores/opengl-cores.md'
419+
- 'Core Options Translation': 'development/cores/core-options-translation.md'
419420
- 'Core-Specific Docs':
420421
- 'Nintendo - GameCube/Wii (Dolphin)': 'development/cores/core-specific/dolphin.md'
421422
- 'Nintendo - GameCube/Wii (Ishiiruka)': 'development/cores/core-specific/ishiiruka.md'

0 commit comments

Comments
 (0)