From dea263a8ae42ae0281e571ff511001cfa1124846 Mon Sep 17 00:00:00 2001 From: Kat <65649991+00-kat@users.noreply.github.com> Date: Fri, 27 Feb 2026 09:31:31 +1100 Subject: [PATCH 1/5] =?UTF-8?q?Correct=20=E2=80=9Ci.e.=20de,=20es,=20and?= =?UTF-8?q?=20fr=E2=80=9D=20to=20use=20=E2=80=9Ce.g=E2=80=9D.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit That isn't a rephrasing of “language codes”, but rather lists examples. --- po/README_TRANSLATORS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/po/README_TRANSLATORS.md b/po/README_TRANSLATORS.md index ab889a3f0..b5a6df639 100644 --- a/po/README_TRANSLATORS.md +++ b/po/README_TRANSLATORS.md @@ -38,7 +38,7 @@ 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. +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 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). From 848d8afecc71f63cf81a3698cdf655fc7be32480 Mon Sep 17 00:00:00 2001 From: Kat <65649991+00-kat@users.noreply.github.com> Date: Fri, 27 Feb 2026 09:53:35 +1100 Subject: [PATCH 2/5] Document common mistakes in translations. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit trag1c or I point these out manually whenever we see them, but they're extremely common and probably deserve being explicitly documented. “Style Guide” was made sentence case because no other title is in title case. Before anyone comments: I use “full stop” instead of “period” because the Unicode Character Database uses “full stop” instead of “period”, and I avoid “dot” because Unicode has a plethora of dots. --- po/README_TRANSLATORS.md | 49 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/po/README_TRANSLATORS.md b/po/README_TRANSLATORS.md index b5a6df639..28a491d53 100644 --- a/po/README_TRANSLATORS.md +++ b/po/README_TRANSLATORS.md @@ -103,8 +103,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 @@ -150,7 +151,7 @@ translation file that you created and `Y` is your [localization team name](#loca +/po/X.po @ghostty-org/Y ``` -## Style Guide +## Style guide These are general style guidelines for translations. Naturally, the specific recommended standards will differ based on the specific language/locale, @@ -187,3 +188,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. From d50368137f9885cd9fc19f188b5ad3b42bcbdf82 Mon Sep 17 00:00:00 2001 From: Kat <65649991+00-kat@users.noreply.github.com> Date: Fri, 27 Feb 2026 10:58:03 +1100 Subject: [PATCH 3/5] Elaborate on viewing translations. Documenting `--language` was suggested by @Filip7 in https://github.com/ghostty-org/ghostty/pull/10976#issuecomment-3969285334 --- po/README_TRANSLATORS.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/po/README_TRANSLATORS.md b/po/README_TRANSLATORS.md index 28a491d53..a951a0ddf 100644 --- a/po/README_TRANSLATORS.md +++ b/po/README_TRANSLATORS.md @@ -136,7 +136,8 @@ 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` @@ -151,6 +152,26 @@ translation file that you created and `Y` is your [localization team name](#loca +/po/X.po @ghostty-org/Y ``` +## 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. + ## Style guide These are general style guidelines for translations. Naturally, the specific From d68f51672e48a3c27ce2e0a2ffda6132d5acbe7d Mon Sep 17 00:00:00 2001 From: Kat <65649991+00-kat@users.noreply.github.com> Date: Fri, 27 Feb 2026 12:06:30 +1100 Subject: [PATCH 4/5] Prefer present over future tense in translators' guide. --- po/README_TRANSLATORS.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/po/README_TRANSLATORS.md b/po/README_TRANSLATORS.md index a951a0ddf..88fbf1777 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 +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. @@ -50,9 +50,9 @@ 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`). +Every locale has 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 @@ -175,8 +175,8 @@ the right click menu. ## 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.** From f833928fcdc2e47c356d4a4aacfaad1b5d8baf94 Mon Sep 17 00:00:00 2001 From: Kat <65649991+00-kat@users.noreply.github.com> Date: Fri, 27 Feb 2026 11:56:50 +1100 Subject: [PATCH 5/5] Document localization teams. --- po/README_TRANSLATORS.md | 68 ++++++++++++++++++++++++++++++---------- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/po/README_TRANSLATORS.md b/po/README_TRANSLATORS.md index 88fbf1777..4ed877e1e 100644 --- a/po/README_TRANSLATORS.md +++ b/po/README_TRANSLATORS.md @@ -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 has 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_ @@ -140,17 +134,9 @@ 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): - -```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 -``` +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 @@ -172,6 +158,54 @@ 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/yy_ZZ +``` + +`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