diff --git a/po/README_TRANSLATORS.md b/po/README_TRANSLATORS.md index ab889a3f0a..4ed877e1e3 100644 --- a/po/README_TRANSLATORS.md +++ b/po/README_TRANSLATORS.md @@ -37,10 +37,10 @@ With this, you're ready to localize! ## 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. +A locale name always consists of a [two letter language +code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) (e.g. `de`, `es`, `fr`). Sometimes, for languages that have regional variations -(such as `zh` and `es`), the locale name will include a [two letter +(such as `zh` and `es`), the locale name includes 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. @@ -48,12 +48,6 @@ 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_ @@ -103,8 +97,9 @@ Lines beginning with `#` are comments, of which there are several kinds: affect translators in other locales. The first entry of the `.po` file has an empty `msgid`. This entry is special -as it stores the metadata related to the `.po` file itself. You usually do -not need to modify it. +as it stores the metadata related to the `.po` file itself. You should update +`PO-Revision-Date` and `Last-Translator` once you have finished your edits, but +you normally do not need to modify other metadata. ## Creating new translation files @@ -135,26 +130,87 @@ const locales = [_][]const u8{ } ``` -You should then be able to run `zig build run` and see your translations in action! +You should then be able to run `zig build run` and see your translations in +action! See the ["Viewing translations" section](#viewing-translations) below. 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): +update the `CODEOWNERS` file. This is described in more detail in the +["Localization teams" section](#localization-teams)—don't forget to read that +section before submitting a pull request! + +## Viewing translations + +> [!NOTE] +> The localization system is not yet implemented for macOS, so it is not +> possible to view your translations there. + +Simply run `zig build run`. Ghostty uses your system language by default; if +your translations are of the language of your system, use +`zig build run -- --language=X` (where `X` is your locale name). You can +alternatively set the `LANGUAGE` environment variable to your locale name. + +On some desktop environments, such as KDE Plasma, Ghostty uses server-side +decorations by default. This hides many strings from the UI, which is +undesirable when viewing your translations. You can force Ghostty to use +client-side decorations with `zig build run -- --window-decoration=client`. + +Some strings are present in multiple places! A notable example is the context +menus: the hamburger menu in the header bar duplicates many strings present in +the right click menu. + +## Localization teams + +Every locale has a localization team consisting of the locale's maintainers. +These maintainers review contributions to their locale's translations, and are +responsible for translating new strings when requested: occasionally, all locale +maintainers are pinged and requested to translate missing strings. + +The primary purposes of being a locale maintainer are a declaration of +_commitment_ to their upkeep, and being _informed_ of updates or update requests +of the translations, via GitHub's review requests or @mentions. + +So that future updates to a locale are possible, each localization team must +have at least two members. If you are introducing a new language, please +**consider volunteering** to be a part of the localization team, by mentioning +that you are willing to be a part of it in the pull request description! You, +and all reviewers, will be offered to join the locale team before the pull +request to add the new language is merged, but this denotes your dedication +upfront—for a pull request adding a new language to be merged, it needs at least +one review from a speaker of that language _and_ at least two localization team +members. No one is _required_ to join a localization team, even if they +introduced support for the language. + +### `CODEOWNERS` + +Localization teams are represented as teams in the Ghostty GitHub organization. +GitHub reads a `CODEOWNERS` file, which maps files to teams, to determine +identify relevant maintainers. When **introducing support for a language**, you +should add the `.po` file to `CODEOWNERS`. + +To do this, find the `# Localization` section near the bottom of the file, and +add a line like so: ```diff # Localization /po/README_TRANSLATORS.md @ghostty-org/localization /po/com.mitchellh.ghostty.pot @ghostty-org/localization /po/zh_CN.po @ghostty-org/zh_CN -+/po/X.po @ghostty-org/Y ++/po/X.po @ghostty-org/yy_ZZ ``` -## Style Guide +`X.po` here is the name of the translation file you created. Unlike the +translation file's name, localization team names **always include a language and +a country code**; `yy` here is the _language code_, and `ZZ` is the _country +code_. + +When adding a new entry, try to keep the list in **alphabetical order** if +possible. + +## Style guide These are general style guidelines for translations. Naturally, the specific -recommended standards will differ based on the specific language/locale, -but these should serve as a baseline for the tone and voice of any translation. +recommended standards differ based on the specific language/locale, but these +should serve as a baseline for the tone and voice of any translation. - **Prefer an instructive, yet professional tone.** @@ -187,3 +243,45 @@ but these should serve as a baseline for the tone and voice of any translation. [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/guidelines/writing-style.html) on Linux, and [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/writing) on macOS. + +## Common issues + +Some mistakes are frequently made during translation. The most common ones are +listed below. + +### Unicode ellipses + +English source strings use the ellipses character, `…`, instead of three full +stops, `...`. If your language uses ellipses, use the ellipses character instead +of three full stops in your translations. You can copy this character from the +English source string itself. + +### Title case + +Title case is a feature of English writing where most words start with a capital +letter: This Clause Is Written In Title Case. It is commonly found in titles, +hence its name; however, English is one of the only languages that uses title +case. If your language does not use title case, **do not use title case for the +sake of copying the English source**. Please use the casing conventions of your +language instead. + +### `X-Generator` field + +Many `.po` file editors add an `X-Generator` field to the metadata section. +These should be removed as other translators might overwrite them when using +a different editor, and some (such as Poedit) update the line when a different +_version_ is used—this adds unnecessary changes to the diff. + +You can remove the `X-Generator` field by simply deleting that line from the +file. + +### Updating metadata (revision date) + +It is very easy to overlook the `PO-Revision-Date` field in the metadata at the +top of the file. Please update this when you are done modifying the +translations! + +Depending on who last translated the file, the `Last-Translator` field might +also need updating: make sure it has your name and email. Finally, if your name +and email are not present in the copyright comment at the top of the file, +consider adding it there.