loading up the forgejo repo on tangled to test page performance
chore(i18n): update contributing documentation with JSON format (#7499)
Things have changed and the readme file in `locale` became significantly less relevant, suggesting things like
> When you work on Forgejo features, you should only modify `locale_en-US.ini`.
Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/7499
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: 0ko <0ko@noreply.codeberg.org>
Co-committed-by: 0ko <0ko@noreply.codeberg.org>
+51
-18
+1
-18
options/locale/readme.md
+1
-18
options/locale/readme.md
···
1
-
# Forgejo translations
2
-
3
-
This directory contains all .INI translations.
4
-
5
-
## Working on base language
6
-
7
-
When you work on Forgejo features, you should only modify `locale_en-US.ini`.
8
-
9
-
* consult https://forgejo.org/docs/next/contributor/localization-english/
10
-
* add strings when your change requires doing so
11
-
* remove strings when your change renders them unused
12
-
13
-
## Working on other languages
14
-
15
-
Translations are done on Codeberg Translate and not via individual pull requests.
16
-
17
-
* consult https://forgejo.org/docs/next/contributor/localization/
18
-
* see the project: https://translate.codeberg.org/projects/forgejo/forgejo/
1
+
See [locale_readme.md](../locale_readme.md) for modification instructions.
19
2
20
3
## Attribution
21
4
+50
options/locale_readme.md
+50
options/locale_readme.md
···
1
+
# Forgejo translations
2
+
3
+
All translations are stored in directories `locale` and `locale_next`.
4
+
5
+
`locale` is a historical directory that contains translations in INI format. Forgejo inherited it from Gitea, and Gitea inherited it from Gogs.
6
+
7
+
Because the INI format had many issues and prevented good translatability, in early 2025 Forgejo started switching to a new format - `go-i18n`+`json`.
8
+
9
+
## Working on base language
10
+
11
+
Here are some tips:
12
+
* when working on non-i18n changes, only change `en-US` files
13
+
* non-base files are normally modified through Weblate. We appreciate the intention to provide localization for the change you're working on, however, modifying those files leads to merge conflicts with Weblate that aren't easy to resolve. [Learn about translating Forgejo](#working-on-other-languages).
14
+
* when new strings are added, it's preferred that they're added to `locale_en-US.json`
15
+
* when strings are modified in `locale_en-US.ini`, it's preferred that they stay here because moving them around is complicated
16
+
* make sure to remove strings if your change renders them unused
17
+
* consult https://forgejo.org/docs/next/contributor/localization-english/
18
+
19
+
### JSON translations
20
+
21
+
It is preferred that all new strings added to Forgejo UI are added to the JSON translations instead of INI.
22
+
23
+
Even though Forgejo parser supports nested sections, linters and Weblate do not. Because of this, most strings need to have all sections flattened into their keys like so:
24
+
```json
25
+
"some.nested.section.key": "UI text"
26
+
```
27
+
28
+
However, plural variations of a string, if it has any, are stored in a nested dictionary:
29
+
```json
30
+
"some.nested.section.key": {
31
+
"one": "%d comment",
32
+
"other": "%d comments"
33
+
}
34
+
```
35
+
36
+
> [!IMPORTANT]
37
+
> Please avoid adding unnecessary sections to the keys. Sections like `repo` are vague and represent a large part of the codebase. Keep the sections scoped to where or how the strings are really used, like `user_settings` or `error`.
38
+
39
+
> [!TIP]
40
+
> Due to the flat sections, you can easily find both JSON strings and their usages in the codebase by grepping an entire key.
41
+
42
+
> [!TIP]
43
+
> 3rd party software can determine whether string has plural variations or not from type of it's value in `en-US.json`.
44
+
45
+
## Working on other languages
46
+
47
+
Translations are done on Codeberg Translate and not via individual pull requests.
48
+
49
+
* consult https://forgejo.org/docs/next/contributor/localization/
50
+
* see the project: https://translate.codeberg.org/projects/forgejo/