Document plural forms and translation context in Localization using spreadsheets

[Calinou]

• Wrap localization pages to around 80 characters.

---

• See Improve CSV translations godot#112073.

Note that I can't get this to work locally, see godotengine/godot#112073 (comment). I'm running into the same issue with plurals according to the example CSV given.

Also, is it possible to make either of these features work when using IDs for translation keys instead of plain English strings? We still recommend using IDs for CSV translation in general, so it's strange to see the documentation suddenly shift to English IDs with no explanation.

[mhilbrunner]

@Calinou This needs a rebase now after the CI was fixed

[mhilbrunner]

cc @timothyqiu @bruvzg Would be great if we could get either of you to give this a brief glance :) (Also see the questions in the PR description)

[timothyqiu]

Note that I can't get this to work locally, see godotengine/godot#112073 (comment). I'm running into the same issue with plurals according to the example CSV given.

I can't reproduce the problem. Try the test project here: godotengine/godot#112073 (comment)

is it possible to make either of these features work when using IDs for translation keys instead of plain English strings?

It already works.

Generally speaking, IDs shouldn't be ambiguous, right?

# This already works.
tr("SOME_ID", "Context A")
tr("SOME_ID", "Context B")

# But this is more ideal, and can use auto-translation.
tr("CONTEXT_A_SOME_ID")
tr("CONTEXT_B_SOME_ID")

For plurals, I'd say tr_n() models the gettext ngettext() and is therefore designed for plain English strings.

It's a plural message as long as ?plural is non-empty. So I'd suggest setting it to something consistent and meaningful when using IDs.

# This already works.
tr_n("SOME_ID", "Plural", n)
tr_n("ANOTHER_ID", "Plural", n)

key,?plural,en
SOME_ID,Plural,Singular Form
,,Plural Form
ANOTHER_ID,Plural,Another singular form
,,Another plural form

it's strange to see the documentation suddenly shift to English IDs with no explanation.

In the class reference of ResourceImporterCSVTranslation, I used this as an introduction:

Although keys in the first column typically use uppercase string identifiers,
it is not uncommon to directly use strings appearing in the game as keys.

Since both context and plural functionality require the use of tr() or tr_n() in the script, I recommend mentioning these functions in the documentation, like in the class ref.

[mhilbrunner]

Thank you, and thanks to the reviewers! Merged.