Translation improvements: CLDR Plurals + Translatables

docs/content/doc/features/localization.en-us.md

@@ -31,3 +31,70 @@ After a translation has been accepted, it will be reflected in the main reposito
 At the time of writing, this means that a changed translation may not appear until the following Gitea release.
 
 If you use a bleeding edge build, it should appear as soon as you update after the change is synced.
+
+## Plurals
+
+Prior to version 1.18, Gitea handled plurals using the .TrN function which has some
+built in rules for managing plurals but is unable to properly all languages.
+
+From 1.18 we will migrate to use the CLDR formulation.
+
+Translation keys which handle plurals should be marked with a `_plural` suffix. This
+will allow autogeneration of the various forms using go templates, e.g.
+
+```ini
+form.reach_limit_of_creation_plural = You have already reached your limit of %d {{if .One}}repository{{else}}repositories{{end}}.
+```
+
+Only the `form` is provided to this template - not the operand value itself. This is to allow autogeneration of the forms at time of loading.
+
+These will be compiled to various different keys based on the available formats in the
+language. e.g. assuming the above key is in the English locale it becomes:
+
+```ini
+form.reach_limit_of_creation_plural_one = You have already reached your limit of %d repository.
+form.reach_limit_of_creation_plural_other = You have already reached your limit of %d repositories.
+
+```
+
+If the template format is too cumbersome forms can be directly created and they will
+be used in preference to the template generated variants.
+
+These keys should be used with the `.TrPlural` function. (Ordinals can be handled with `.TrOrdinal`.)
+
+Each language has different numbers of plural forms, in English (and a number of other
+languages) there are two plural forms:
+
+* `One`: This matches the singular form.
+* `Other`: This matches the plural form.
+
+Other languages, e.g. Mandarin, have no plural forms, and others many more.
+
+The possible forms are:
+
+* `Other` - the most common form and will often match to standard plural form.
+* `Zero` - matches a zeroth form, which in Latvian would match the form used for 10-20, 30 and so on.
+* `One` - matches the singular form in English, but in Latvian matches the form used for 1, 21, 31 and so on.
+* `Two` - matches the dual form used in for example Arabic for 2 items, but also more complexly in Celtic languages.
+* `Few` - matches the form used in Arabic for 3-10, 103-110, and the ternary form in Celtic languages. In Russian and Ukranian for 2-4, 22-24.
+* `Many` - matches the form used for large numbers in romance lanaguages like French, e.g. 1 000 000 *de* chat*s*, but in Russian and Ukranian it handles 0, 5~19, 100, 1000 and so on.
+
+Some plural forms are only relevant if the object being counted is of a certain
+grammatical gender or in certain tenses. Write your translation template appropriately to take account of this using `not` or `and` as appropriately.
+
+Translators may want to review the CLDR information for their language or look at
+`modules/translation/i18n/plurals/generate/plurals.xml`.
+
+Ordinal forms, e.g. 1st, 2nd, 3rd and so on can be handled with `.TrOrdinal`. These
+have the same forms as the plural forms, and we will use `_ordinal` as a base suffix
+in future.
+
+If the provided key does not have the `_plural` suffix or its format template is invalid, the specific per plural forms must be provided explicitly. The plural key fallback hierarchy is as follows:
+
+1. `${key}_${form}` in the locale.
+2. `${key}_other` in the locale.
+3. `${key}` in the locale.
+4. `${key}_${form}` in the default locale.
+5. `${key}_other` in the default locale.
+6. `${key}` in the default locale.
+7. Use the `${key}_${form}` directly as the format.

modules/charset/escape_test.go

@@ -138,6 +138,9 @@ type nullLocale struct{}
 func (nullLocale) Language() string                                                   { return "" }
 func (nullLocale) Tr(key string, _ ...interface{}) string                             { return key }
 func (nullLocale) TrN(cnt interface{}, key1, keyN string, args ...interface{}) string { return "" }
+func (nullLocale) HasKey(_ string) bool                                               { return false }
+func (nullLocale) TrPlural(cnt interface{}, key string, args ...interface{}) string   { return key }
+func (nullLocale) TrOrdinal(cnt interface{}, key string, args ...interface{}) string  { return key }
 
 var _ (translation.Locale) = nullLocale{}
 

modules/csv/csv_test.go

@@ -561,6 +561,14 @@ func (l mockLocale) TrN(_cnt interface{}, key1, _keyN string, _args ...interface
 	return key1
 }
 
+func (l mockLocale) TrPlural(_cnt interface{}, key string, _args ...interface{}) string {
+	return key
+}
+
+func (l mockLocale) TrOrdinal(_cnt interface{}, key string, _args ...interface{}) string {
+	return key
+}
+
 func TestFormatError(t *testing.T) {
 	cases := []struct {
 		err             error

modules/test/context_tests.go

@@ -99,6 +99,10 @@ func (l mockLocale) Language() string {
 	return "en"
 }
 
+func (l mockLocale) HasKey(_ string) bool {
+	return false
+}
+
 func (l mockLocale) Tr(s string, _ ...interface{}) string {
 	return s
 }
@@ -107,6 +111,14 @@ func (l mockLocale) TrN(_cnt interface{}, key1, _keyN string, _args ...interface
 	return key1
 }
 
+func (l mockLocale) TrPlural(_cnt interface{}, key string, _args ...interface{}) string {
+	return key
+}
+
+func (l mockLocale) TrOrdinal(_cnt interface{}, key string, _args ...interface{}) string {
+	return key
+}
+
 type mockResponseWriter struct {
 	httptest.ResponseRecorder
 	size int