i18n: rename .po files

CODEOWNERS

@@ -164,32 +164,32 @@
 # Localization
 /po/README_TRANSLATORS.md @ghostty-org/localization
 /po/com.mitchellh.ghostty.pot @ghostty-org/localization
-/po/bg_BG.UTF-8.po @ghostty-org/bg_BG
-/po/ca_ES.UTF-8.po @ghostty-org/ca_ES
-/po/de_DE.UTF-8.po @ghostty-org/de_DE
-/po/es_BO.UTF-8.po @ghostty-org/es_BO
-/po/es_AR.UTF-8.po @ghostty-org/es_AR
-/po/fr_FR.UTF-8.po @ghostty-org/fr_FR
-/po/hu_HU.UTF-8.po @ghostty-org/hu_HU
-/po/id_ID.UTF-8.po @ghostty-org/id_ID
-/po/ja_JP.UTF-8.po @ghostty-org/ja_JP
-/po/mk_MK.UTF-8.po @ghostty-org/mk_MK
-/po/nb_NO.UTF-8.po @ghostty-org/nb_NO
-/po/nl_NL.UTF-8.po @ghostty-org/nl_NL
-/po/pl_PL.UTF-8.po @ghostty-org/pl_PL
-/po/pt_BR.UTF-8.po @ghostty-org/pt_BR
-/po/ru_RU.UTF-8.po @ghostty-org/ru_RU
-/po/tr_TR.UTF-8.po @ghostty-org/tr_TR
-/po/uk_UA.UTF-8.po @ghostty-org/uk_UA
-/po/zh_CN.UTF-8.po @ghostty-org/zh_CN
-/po/ga_IE.UTF-8.po @ghostty-org/ga_IE
-/po/ko_KR.UTF-8.po @ghostty-org/ko_KR
-/po/he_IL.UTF-8.po @ghostty-org/he_IL
-/po/it_IT.UTF-8.po @ghostty-org/it_IT
-/po/lt_LT.UTF-8.po @ghostty-org/lt_LT
-/po/lv_LV.UTF-8.po @ghostty-org/lv_LV
-/po/zh_TW.UTF-8.po @ghostty-org/zh_TW
-/po/hr_HR.UTF-8.po @ghostty-org/hr_HR
+/po/bg.po @ghostty-org/bg_BG
+/po/ca.po @ghostty-org/ca_ES
+/po/de.po @ghostty-org/de_DE
+/po/es_AR.po @ghostty-org/es_AR
+/po/es_BO.po @ghostty-org/es_BO
+/po/fr.po @ghostty-org/fr_FR
+/po/ga.po @ghostty-org/ga_IE
+/po/he.po @ghostty-org/he_IL
+/po/hr.po @ghostty-org/hr_HR
+/po/hu.po @ghostty-org/hu_HU
+/po/id.po @ghostty-org/id_ID
+/po/it.po @ghostty-org/it_IT
+/po/ja.po @ghostty-org/ja_JP
+/po/ko.po @ghostty-org/ko_KR
+/po/lt.po @ghostty-org/lt_LT
+/po/lv.po @ghostty-org/lv_LV
+/po/mk.po @ghostty-org/mk_MK
+/po/nb.po @ghostty-org/nb_NO
+/po/nl.po @ghostty-org/nl_NL
+/po/pl.po @ghostty-org/pl_PL
+/po/pt.po @ghostty-org/pt_BR
+/po/ru.po @ghostty-org/ru_RU
+/po/tr.po @ghostty-org/tr_TR
+/po/uk.po @ghostty-org/uk_UA
+/po/zh_CN.po @ghostty-org/zh_CN
+/po/zh_TW.po @ghostty-org/zh_TW
 
 # Packaging - Snap
 /snap/ @ghostty-org/snap

po/README_TRANSLATORS.md

@@ -35,28 +35,45 @@ Written by Ulrich Drepper.
 
 With this, you're ready to localize!
 
-## Editing translation files
+## Locale names
+
+A locale name will always consist of a [two letter language
+code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) (i.e.
+`de`, `es`, `fr`). Sometimes, for languages that have regional variations
+(such as `zh` and `es`), the locale name will include a [two letter
+country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
+One example is `es_AR` for Spanish as spoken in Argentina.
+
+Full locale names are more complicated, but Ghostty does not use all parts. [The
+`gettext` documentation](https://www.gnu.org/software/gettext/manual/gettext.html#Locale-Names-1)
+has more information on locale names.
+
+## Localization team name
+
+Every locale will have a localization team that helps keep localizations up to
+date. Localization team names _always_ consist of a language code and a country
+code (e.g. `de_DE` or `zh_CN`).
+
+## Translation file names
 
 All translation files lie in the `po/` directory, including the main _template_
 file called `com.mitchellh.ghostty.pot`. **Do not edit this file.** The
-template is generated automatically from Ghostty's code and resources, and are
+template is generated automatically from Ghostty's code and resources, and is
 intended to be regenerated by code contributors. If there is a problem with
 the template file, please reach out to a code contributor.
 
-Instead, only edit the translation file corresponding to your language/locale,
-identified via its _locale name_: for example, `de_DE.UTF-8.po` would be the
-translation file for German (language code `de`) as spoken in Germany (country
-code `DE`). The GNU `gettext` manual contains
-[further information about locale names](https://www.gnu.org/software/gettext/manual/gettext.html#Locale-Names-1),
-including a list of language and country codes.
+Translation file names consist of the locale name and the extension
+`.po`. For example: `de.po`, `zh_CN.po`.
+
+## Editing translation files
 
 > [!NOTE]
 >
 > If the translation file for your locale does not yet exist, see the
 > ["Creating new translation files" section](#creating-new-translation-files)
 > of this document on how to create one.
 
-The `.po` file contains a list of entries that look like this:
+The translation file contains a list of entries that look like this:
 
 ```po
 #. Translators: the category in the right-click context menu that contains split items for all directions
@@ -93,70 +110,44 @@ not need to modify it.
 
 You can use the `msginit` tool to create new translation files.
 
-Run the command below, optionally replacing `$LANG` with the name of a locale
-that is _different_ to your system locale, or if the `LANG` environmental
-variable is not set.
+Run the command below, replacing `X` with your [locale name](#locale-names).
 
 ```console
-$ msginit -i po/com.mitchellh.ghostty.pot -l $LANG -o "po/$LANG.po"
+$ msginit -i po/com.mitchellh.ghostty.pot -l X -o "po/X.po"
 ```
 
-> [!NOTE]
->
-> Ghostty enforces the convention that all parts of the locale, including the
-> language code, country code, encoding, and possible regional variants
-> **must** be communicated in the file name. Files like `pt.po` are not
-> acceptable, while `pt_BR.UTF-8.po` is.
->
-> This is to allow us to more easily accommodate regional variants of a
-> language in the future, and to reject translations that may not be applicable
-> to all speakers of a language (e.g. an unqualified `zh.po` may contain
-> terminology specific to Chinese speakers in Mainland China, which are not
-> found in Taiwan. Using `zh_CN.UTF-8.po` would allow that difference to be
-> communicated.)
-
-> [!WARNING]
->
-> **Make sure your selected locale uses the UTF-8 encoding, as it is the sole
-> encoding supported by Ghostty and its dependencies.**
->
-> For backwards compatibility reasons, some locales may default to a non-UTF-8
-> encoding when an encoding is not specified. For instance, `de_DE` defaults
-> to using the legacy ISO-8859-1 encoding, which is incompatible with UTF-8.
-> You need to manually instruct `msginit` to use UTF-8 in these instances,
-> by appending `.UTF-8` to the end of the locale name (e.g. `de_DE.UTF-8`).
-
 `msginit` may prompt you for other information such as your email address,
 which should be filled in accordingly. You can then add your translations
 within the newly created translation file.
 
 Afterwards, you need to update the list of known locales within Ghostty's
-build system. To do so, open `src/os/i18n_locales.zig` and find the list
-of locales after the comments, then add the full locale name into the list.
+build system. To do so, open `src/os/i18n_locales.zig` and find the list of
+locale names after the comments, then add your locale name into the list.
 
-The order matters, so make sure to place your locale in the correct position.
-Read the comments present in the file for more details on the order. If you're
-unsure, place it at the end of the list.
+The order matters, so make sure to place your locale name in the correct
+position. Read the comments present in the file for more details on the order.
+If you're unsure, place it at the end of the list.
 
 ```zig
 const locales = [_][]const u8{
-    "zh_CN.UTF-8",
-    // <- Add your locale here (probably)
+    "zh_CN",
+    // <- Add your locale name here (probably)
 }
 ```
 
-You should then be able to run `zig build` and see your translations in action!
+You should then be able to run `zig build run` and see your translations in action!
 
-Before opening a pull request with the new translation file, you should also add
-your locale to the `CODEOWNERS` file. Find the `# Localization` section near the
-bottom and add a line like so (where `xx_YY` is your locale):
+Before opening a pull request with the new translation file, you should also
+add your translation file to the `CODEOWNERS` file. Find the `# Localization`
+section near the bottom and add a line like so (where `X.po` is the name of the
+translation file that you created and `Y` is your [localization team name](#localization-team-name):
 
 ```diff
  # Localization
  /po/README_TRANSLATORS.md @ghostty-org/localization
  /po/com.mitchellh.ghostty.pot @ghostty-org/localization
- /po/zh_CN.UTF-8.po @ghostty-org/zh_CN
-+/po/xx_YY.UTF-8.po @ghostty-org/xx_YY
+ /po/zh_CN.po @ghostty-org/zh_CN
++/po/X.po @ghostty-org/Y
 ```
 
 ## Style Guide

src/os/i18n_locales.zig

@@ -28,30 +28,30 @@
 /// we don't have a good way to determine this. We can always reorder
 /// with some data.
 pub const locales = [_][:0]const u8{
-    "zh_CN.UTF-8",
-    "de_DE.UTF-8",
-    "fr_FR.UTF-8",
-    "ja_JP.UTF-8",
-    "nl_NL.UTF-8",
-    "nb_NO.UTF-8",
-    "ru_RU.UTF-8",
-    "uk_UA.UTF-8",
-    "pl_PL.UTF-8",
-    "ko_KR.UTF-8",
-    "mk_MK.UTF-8",
-    "tr_TR.UTF-8",
-    "id_ID.UTF-8",
-    "es_BO.UTF-8",
-    "es_AR.UTF-8",
-    "pt_BR.UTF-8",
-    "ca_ES.UTF-8",
-    "it_IT.UTF-8",
-    "bg_BG.UTF-8",
-    "ga_IE.UTF-8",
-    "hu_HU.UTF-8",
-    "he_IL.UTF-8",
-    "zh_TW.UTF-8",
-    "hr_HR.UTF-8",
-    "lt_LT.UTF-8",
-    "lv_LV.UTF-8",
+    "zh_CN",
+    "de",
+    "fr",
+    "ja",
+    "nl",
+    "nb",
+    "ru",
+    "uk",
+    "pl",
+    "ko",
+    "mk",
+    "tr",
+    "id",
+    "es_BO",
+    "es_AR",
+    "pt",
+    "ca",
+    "it",
+    "bg",
+    "ga",
+    "hu",
+    "he",
+    "zh_TW",
+    "hr",
+    "lt",
+    "lv",
 };