feat(dist): generate completions, editor syntax, man pages, translations
Ports Ghostty's build-data helpers (main_build_data.zig, src/extra/*, build/mdgen) as the ghostty-build-data binary: bash/zsh/fish completions, Vim syntax/ftdetect/ftplugin/compiler, Sublime syntax (also used by bat), terminfo source and ghostty(1)/ghostty(5) markdown. With the version set to the installed 1.3.1-arch2, all generated files are byte-identical to the installed Ghostty's. - `just docs` renders man pages and HTML with pandoc. - po/: Ghostty's 29 translation catalogs; `just locales` compiles them into the com.mitchellh.ghostty gettext domain. - `just install PREFIX FLATPAK SYSTEM_PACKAGE` installs everything incl. terminfo text/termcap outputs and mirrors GhosttyResources.zig install modes (Flatpak D-Bus template without systemd; lib/systemd/user for system packages). - Build metadata (version, tip/stable channel, commit, build mode) is derived at build time like build_config.zig; GTK/libadwaita compile-time versions come from pkg-config instead of constants. Test Plan: - cargo run -p ghostty-build-data -- +bash | diff - \ /usr/share/bash-completion/completions/ghostty (same for zsh/fish/vim) - just install /tmp/prefix
This commit is contained in:
ddidderr committed
1 parent
79486601b5
commit
2dc1c6028d
56 files changed
+12614
-16
No files matched your search
@@ -0,0 +1,287 @@
|
||||
# Localizing Ghostty: The Translators' Guide
|
||||
|
||||
First of all, thanks for helping us localize Ghostty!
|
||||
|
||||
To begin contributing, please make sure that you have installed `gettext`
|
||||
on your system, which should be available under the `gettext` package
|
||||
for most Linux and macOS package managers.
|
||||
|
||||
You can install `gettext` on Windows in a few ways:
|
||||
|
||||
- Through [an installer](https://mlocati.github.io/articles/gettext-iconv-windows.html);
|
||||
- Through package managers like Scoop (`scoop install gettext`) and
|
||||
WinGet (`winget install gettext`) which repackages the aforementioned installer;
|
||||
- Through Unix-like environments like [Cygwin](https://cygwin.com/cygwin/packages/summary/gettext.html)
|
||||
and [MSYS2](https://packages.msys2.org/base/gettext).
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> Unlike what some tutorials suggest, **we do not recommend installing `gettext`
|
||||
> through GnuWin32**, since it hasn't been updated since 2010 and very likely
|
||||
> does not work on modern Windows versions.
|
||||
|
||||
You can verify that `gettext` has been successfully installed by running the
|
||||
command `gettext -V`. If everything went correctly, you should see an output like this:
|
||||
|
||||
```console
|
||||
$ gettext -V
|
||||
gettext (GNU gettext-runtime) 0.21.1
|
||||
Copyright (C) 1995-2022 Free Software Foundation, Inc.
|
||||
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law.
|
||||
Written by Ulrich Drepper.
|
||||
```
|
||||
|
||||
With this, you're ready to localize!
|
||||
|
||||
## Locale names
|
||||
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
## 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 is
|
||||
intended to be regenerated by code contributors. If there is a problem with
|
||||
the template file, please reach out to a code contributor.
|
||||
|
||||
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 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
|
||||
#: src/apprt/gtk/ui/1.0/menu-surface-context-menu.blp:38
|
||||
# 译注：其他终端程序对 Split 皆有不同翻译，此处采取最直观的翻译方式
|
||||
msgctxt "Context menu"
|
||||
msgid "Split"
|
||||
msgstr "分屏"
|
||||
```
|
||||
|
||||
The `msgid` line contains the original string in English, and the `msgstr` line
|
||||
should contain the translation for your language. Occasionally there will also
|
||||
be a `msgctxt` line that differentiates strings that are identical in English,
|
||||
based on its context.
|
||||
|
||||
Lines beginning with `#` are comments, of which there are several kinds:
|
||||
|
||||
- Pay attention to comments beginning with `#.`. They are comments left
|
||||
by _developers_ providing more context to the string.
|
||||
|
||||
- Comments that begin with `#:` are _source comments_: they link
|
||||
the string to source code or resource files. You normally don't need to
|
||||
consider these in your translations.
|
||||
|
||||
- You may also leave comments of your own to be read by _other translators_,
|
||||
beginning with `# `. These comments are specific to your locale and don't
|
||||
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 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
|
||||
|
||||
You can use the `msginit` tool to create new translation files.
|
||||
|
||||
Run the command below, replacing `X` with your [locale name](#locale-names).
|
||||
|
||||
```console
|
||||
$ msginit -i po/com.mitchellh.ghostty.pot -l X -o "po/X.po"
|
||||
```
|
||||
|
||||
`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
|
||||
locale names after the comments, then add your locale name into 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",
|
||||
// <- Add your locale name here (probably)
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
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 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
|
||||
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 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.**
|
||||
|
||||
In languages that exhibit distinctions based on formality,
|
||||
prefer the formality that is expected of instructive material on the internet.
|
||||
The user should be considered an equal peer of the program and the translator,
|
||||
not an esteemed customer.
|
||||
|
||||
- **Use simple to understand language and avoid jargon.**
|
||||
|
||||
Explain concepts that may be familiar in an English-speaking context,
|
||||
but are uncommon in your language.
|
||||
|
||||
- **Do not overly literally translate foreign concepts to your language.**
|
||||
|
||||
Care should be taken so that your translations make sense to a reader without
|
||||
any background knowledge of the English source text. To _localize_ is to
|
||||
transfer a concept between languages, not to translate each word at face value.
|
||||
|
||||
- **Be consistent with stylistic and tonal choices.**
|
||||
|
||||
Consult the translations made by previous translators, and try to emulate them.
|
||||
Do not overwrite someone else's hard work without substantial justification.
|
||||
|
||||
- **Make Ghostty fit in with surrounding applications.**
|
||||
|
||||
Follow existing translations for terms and concepts if possible, even when
|
||||
they are suboptimal. Follow the writing styles prescribed by the human
|
||||
interface guidelines of each platform Ghostty is available for, including the
|
||||
[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 with a plain text editor.
|
||||
|
||||
### 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.
|
||||
Reference in new issue
Block a user