i18n: Maintain a list of supported languages with metadata

PIG208 · PIG208 · commit 44b878f220c3 · 2025-05-16T17:53:58.000-04:00
This is similar to what we did in zulip-mobile: https://github.com/zulip/zulip-mobile/blob/91f5c3289/src/settings/languages.js
diff --git a/assets/l10n/app_en.arb b/assets/l10n/app_en.arb
@@ -835,6 +835,22 @@
   "@openLinksWithInAppBrowser": {
     "description": "Label for toggling setting to open links with in-app browser"
   },
+  "languageEn": "English",
+  "@languageEn": {
+    "description": "Label for the English language."
+  },
+  "languagePl": "Polish",
+  "@languagePl": {
+    "description": "Label for the Polish language."
+  },
+  "languageRu": "Russian",
+  "@languageRu": {
+    "description": "Label for the Russian language."
+  },
+  "languageUk": "Ukrainian",
+  "@languageUk": {
+    "description": "Label for the Ukrainian language."
+  },
   "pollWidgetQuestionMissing": "No question.",
   "@pollWidgetQuestionMissing": {
     "description": "Text to display for a poll when the question is missing"
diff --git a/docs/translation.md b/docs/translation.md
@@ -25,6 +25,8 @@ is working correctly.
 
 ## Adding new UI strings
 
+<a id="add-string" />
+
 ### Adding a string to the translation database
 
 To add a new string in the UI, start by
@@ -79,6 +81,21 @@ For example:
 `zulipLocalizations.subscribedToNChannels(store.subscriptions.length)`.
 
 
+## Adding a new language
+
+ARB files for new languages are automatically created in Pull Requests generated
+[the update-translations GitHub workflow](/.github/workflows/update-translations.yml).
+However, this won't make them appear in settings.
+
+When a language has a good percentage of strings translated, we should add it to
+settings.  First, if the language tag is 'en-GB', [add a string](#add-string)
+named 'languageNameEnGb'.
+
+Then, update [localizations.dart](/lib/model/localizations.dart) to include
+the new language in `kSelfnamesByLocale` and `localeDisplayName`, following
+the instructions there.
+
+
 ## Hack to enforce locale (for testing, etc.)
 
 For testing the app's behavior in different locales,
diff --git a/lib/generated/l10n/zulip_localizations.dart b/lib/generated/l10n/zulip_localizations.dart
@@ -1226,6 +1226,30 @@ abstract class ZulipLocalizations {
   /// **'Open links with in-app browser'**
   String get openLinksWithInAppBrowser;
 
+  /// Label for the English language.
+  ///
+  /// In en, this message translates to:
+  /// **'English'**
+  String get languageEn;
+
+  /// Label for the Polish language.
+  ///
+  /// In en, this message translates to:
+  /// **'Polish'**
+  String get languagePl;
+
+  /// Label for the Russian language.
+  ///
+  /// In en, this message translates to:
+  /// **'Russian'**
+  String get languageRu;
+
+  /// Label for the Ukrainian language.
+  ///
+  /// In en, this message translates to:
+  /// **'Ukrainian'**
+  String get languageUk;
+
   /// Text to display for a poll when the question is missing
   ///
   /// In en, this message translates to:
diff --git a/lib/generated/l10n/zulip_localizations_ar.dart b/lib/generated/l10n/zulip_localizations_ar.dart
@@ -679,6 +679,18 @@ class ZulipLocalizationsAr extends ZulipLocalizations {
   @override
   String get openLinksWithInAppBrowser => 'Open links with in-app browser';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'No question.';
 
diff --git a/lib/generated/l10n/zulip_localizations_en.dart b/lib/generated/l10n/zulip_localizations_en.dart
@@ -679,6 +679,18 @@ class ZulipLocalizationsEn extends ZulipLocalizations {
   @override
   String get openLinksWithInAppBrowser => 'Open links with in-app browser';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'No question.';
 
diff --git a/lib/generated/l10n/zulip_localizations_ja.dart b/lib/generated/l10n/zulip_localizations_ja.dart
@@ -679,6 +679,18 @@ class ZulipLocalizationsJa extends ZulipLocalizations {
   @override
   String get openLinksWithInAppBrowser => 'Open links with in-app browser';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'No question.';
 
diff --git a/lib/generated/l10n/zulip_localizations_nb.dart b/lib/generated/l10n/zulip_localizations_nb.dart
@@ -679,6 +679,18 @@ class ZulipLocalizationsNb extends ZulipLocalizations {
   @override
   String get openLinksWithInAppBrowser => 'Open links with in-app browser';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'No question.';
 
diff --git a/lib/generated/l10n/zulip_localizations_pl.dart b/lib/generated/l10n/zulip_localizations_pl.dart
@@ -688,6 +688,18 @@ class ZulipLocalizationsPl extends ZulipLocalizations {
   @override
   String get openLinksWithInAppBrowser => 'Otwieraj odnośniki w aplikacji';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'Brak pytania.';
 
diff --git a/lib/generated/l10n/zulip_localizations_ru.dart b/lib/generated/l10n/zulip_localizations_ru.dart
@@ -692,6 +692,18 @@ class ZulipLocalizationsRu extends ZulipLocalizations {
   @override
   String get openLinksWithInAppBrowser => 'Открывать ссылки внутри приложения';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'Нет вопроса.';
 
diff --git a/lib/generated/l10n/zulip_localizations_sk.dart b/lib/generated/l10n/zulip_localizations_sk.dart
@@ -681,6 +681,18 @@ class ZulipLocalizationsSk extends ZulipLocalizations {
   @override
   String get openLinksWithInAppBrowser => 'Open links with in-app browser';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'Bez otázky.';
 
diff --git a/lib/generated/l10n/zulip_localizations_uk.dart b/lib/generated/l10n/zulip_localizations_uk.dart
@@ -692,6 +692,18 @@ class ZulipLocalizationsUk extends ZulipLocalizations {
   String get openLinksWithInAppBrowser =>
       'Відкривати посилання за допомогою браузера додатку';
 
+  @override
+  String get languageEn => 'English';
+
+  @override
+  String get languagePl => 'Polish';
+
+  @override
+  String get languageRu => 'Russian';
+
+  @override
+  String get languageUk => 'Ukrainian';
+
   @override
   String get pollWidgetQuestionMissing => 'Немає питання.';
 
diff --git a/lib/model/localizations.dart b/lib/model/localizations.dart
@@ -1,3 +1,5 @@
+import 'dart:ui';
+
 import '../generated/l10n/zulip_localizations.dart';
 
 abstract final class GlobalLocalizations {
@@ -15,3 +17,60 @@ abstract final class GlobalLocalizations {
   static ZulipLocalizations zulipLocalizations =
     lookupZulipLocalizations(ZulipLocalizations.supportedLocales.first);
 }
+
+/// The mapping, of the locales we offer, to their display name in their own
+/// locale a.k.a. selfname.
+///
+/// [ZulipLocalizations.supportedLocales] can include languages that only have
+/// a few strings translated.  This map should only inlcude sufficiently
+/// translated locales from [ZulipLocalizations.supportedLocales].
+///
+/// The map should be sorted by selfname, to help users find their
+/// language in the UI.  When in doubt how to sort (like between different
+/// scripts, or in scripts you don't know), try to match the order found in
+/// other UIs, like for choosing a language in your phone's system settings.
+///
+/// For the values of selfname, consult Wikipedia:
+///   https://meta.wikimedia.org/wiki/List_of_Wikipedias
+///   https://en.wikipedia.org/wiki/Special:Preferences
+/// or better yet, Wikipedia's own mobile UIs.  Wikipedia is a very
+/// conscientiously international and intercultural project with a lot of
+/// effort going into it by speakers of many languages, which makes it a
+/// useful gold standard for this.
+///
+/// This is adapted from:
+///   https://github.com/zulip/zulip-mobile/blob/91f5c3289/src/settings/languages.js
+///
+/// See also:
+///   * [ZulipLocalizations.localeDisplayName], similar helper that looks up the
+///     localized display name of a locale in an instance of ZulipLocalizations.
+final kSelfnamesByLocale = <Locale, String>{
+  Locale('en'): 'English',
+  Locale('pl'): 'Polski',
+  Locale('ru'): 'Русский',
+  Locale('uk'): 'Українська',
+};
+
+extension ZulipLocalizationsHelper on ZulipLocalizations {
+  /// Look up the localized display name of [locale].
+  ///
+  /// [locale] must be present in [kSelfnamesByLocale].
+  String localeDisplayName(Locale locale) {
+    assert(kSelfnamesByLocale.containsKey(locale), 'Locale not found: $locale');
+    switch (locale.toLanguageTag()) {
+      // When adding a new case, keep this sorted to match the order in
+      // [kSelfnamesByLocale].
+
+      case 'en':
+        return languageEn;
+      case 'pl':
+        return languagePl;
+      case 'ru':
+        return languageRu;
+      case 'uk':
+        return languageUk;
+      default:
+        throw ArgumentError.value(locale, 'locale');
+    }
+  }
+}
diff --git a/test/model/localizations_test.dart b/test/model/localizations_test.dart
@@ -0,0 +1,23 @@
+import 'package:checks/checks.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:zulip/generated/l10n/zulip_localizations.dart';
+import 'package:zulip/model/localizations.dart';
+
+void main() {
+  test('kSelfnamesByLocale', () {
+    for (final locale in kSelfnamesByLocale.keys) {
+      check(ZulipLocalizations.supportedLocales).contains(locale);
+    }
+  });
+
+  test('localeDisplayName only returns for all keys in kSelfnamesByLocale', () {
+    final zulipLocalizations = GlobalLocalizations.zulipLocalizations;
+    for (final locale in ZulipLocalizations.supportedLocales) {
+      kSelfnamesByLocale.containsKey(locale)
+        ? check(() =>
+            zulipLocalizations.localeDisplayName(locale)).returnsNormally()
+        : check(() =>
+            zulipLocalizations.localeDisplayName(locale)).throws<void>();
+    }
+  });
+}
