From d44a76807f6b9777241433f9b1e7bba322635fe8 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Sat, 25 Jul 2026 10:06:25 +0200 Subject: [PATCH 1/5] Remove translations information from contributing guide --- docs/developers/contributing/translations.md | 237 ------------------- docs/developers/index.md | 1 - 2 files changed, 238 deletions(-) delete mode 100644 docs/developers/contributing/translations.md diff --git a/docs/developers/contributing/translations.md b/docs/developers/contributing/translations.md deleted file mode 100644 index 8da45a56d..000000000 --- a/docs/developers/contributing/translations.md +++ /dev/null @@ -1,237 +0,0 @@ -(napari-translations)= - -# Translations - -Starting with version 0.4.7, napari codebase include internationalization -(i18n) and now offers the possibility of installing language packs, which -provide localization (l10n) enabling the user interface to be displayed in -different languages. - -To learn more about the current languages that are in the process of -translation, visit the [language packs repository](https://github.com/napari/napari-language-packs) - -This guide is limited to providing translations to the napari core codebase. -We will soon provide more information on how to make your napari plugins -localizable. - -## How to make strings translatable? - -To make your code translatable (localizable), please use the `trans` helper -provided by the napari utilities. - -```python -from napari.utils.translations import trans -``` - -`trans` is a convenience wrapper on top of the `gettext` module of the -standard library, which provides the l10n and i18n facilities in Python. To -learn more about `gettext` visit the [Python documentation](https://docs.python.org/3/library/gettext.html). - -`trans` provides 4 methods that can be used to handle localization. - -The following examples make use of a widget to illustrate the workflow, but -this also applies to other strings that may be surfaced to the user, e.g. -custom exceptions. - -`f-strings` do not work with localizable strings, so any strings that use them -need to be converted. The [Plural strings section](#plural-strings) -below explains this in more detail. - -### Singular strings - -Strings that need to provide a 1:1 translation, can use the `trans._` method: - -```python -from qtpy.QtWidgets import QComboBox, QWidget - -from napari.utils.translations import trans - - -class SomeWidget(QWidget): - def __init__(self): - self.channel_combo_box = QComboBox(self) - self.channel_combo_box.addItem(trans._('red'), 'red') - self.channel_combo_box.addItem(trans._('green'), 'green') - self.channel_combo_box.addItem(trans._('blue'), 'blue') -``` - -On this example, we add a RGB channel combo box selector. The first argument of -`addItem` is the actual display name of that combobox item, whereas the second -argument is the data associated to that item, in this case the original channel -name. - -For the `English (US)` translation the options displayed would be the same, -since `gettext` uses the source language as the key to find translations. -In this case: - -- red -- green -- blue - -For the `Spanish (Spain)` translation the options displayed would be: - -- rojo -- verde -- azul - -`trans._` is a wrapper on top of [gettext.gettext](https://docs.python.org/3/library/gettext.html#gettext.gettext) with enhanced functionality. - -### Singular strings with context - -Strings that need some additional context to disambiguate the source string, -can use the `trans._p` method: - -The word **Tab** can mean different things in the english language: - -- A spacer, when the `Tab` key of a keyboard is used inside a text editor. -- A tablature, a simplified version of sheet music used for stringed - instruments. -- A user interface graphical element, like the one provide by `QTabWidget`. - -```python -from qtpy.QtWidgets import QComboBox, QWidget - -from napari.utils.translations import trans - - -class SomeWidget(QWidget): - def __init__(self): - self.context_combo_box = QComboBox(self) - self.context_combo_box.addItem( - trans._p( - 'character', - 'tab', - ), - 'tab', - ) - self.context_combo_box.addItem(trans._p('music', 'tab'), 'tab') - self.context_combo_box.addItem(trans._p('ui-element', 'tab'), 'tab') -``` - -On this example, we add the word `tab` three time to a combo box selector. -The first argument of `trans._p` provides the context string that will help -to disambiguate the translation. - -For the `English (US)` translation the options displayed would be the same, -since `gettext` uses the source language as the key to find translations. In -this case: - -- tab -- tab -- tab - -For the `Spanish (Spain)` translation the options displayted would be: - -- tabulación -- tablatura -- pestaña - -`trans._p` is a wrapper on top of [gettext.pgettext](https://docs.python.org/3/library/gettext.html#gettext.pgettext) with enhanced functionality. - -### Plural strings - -Some strings or sentences might need to be handled differently when needing -pluralization, that is depending on the amount of items included in the -string. - -```python -from qtpy.QtWidgets import QLabel, QWidget - -from napari.utils.translations import trans - - -class SomeWidget(QWidget): - def __init__(self, amount): - string = trans._n('{n} item', '{n} items', n=amount) - self.label = QLabel(string) -``` - -On this example, the label string depends on the `n` parameter. The -first argument of `trans._n` provides the singular version of the string. -The second argument provides the plural version of the string. The third -argument provides the quantity that will allow to know which string should -be used, in this case `amount`. Notice that by default `trans._n` will try to -interpolate the value of `n` in the string, if found. - -For the `English (US)` translation the string displayed for different values -of `amount` would be: - -- For `amount=0`, `"0 items"` -- For `amount=1`, `"1 item"` -- For `amount=2`, `"2 items"` - -For the `Spanish (Spain)` translation the options displayted would be: - -- For `amount=0`, `"0 ítems"` -- For `amount=1`, `"1 ítem"` -- For `amount=2`, `"2 ítems"` - -Take into account that different languages will handle pluralization -differently. Having clear variable names within strings (e.g. `{amount}`) of -what the variable represents makes the internationalization process much -easier and pleasant for translators. - -`trans._n` is a wrapper on top of [gettext.ngettext](https://docs.python.org/3/library/gettext.html#gettext.ngettext) with enhanced functionality. - -### Plural strings with context - -This is similar to plural strings, but an additional context can be supplied -as explained in the [Singular strings with context](#singular-strings-with-context) section. - -## Deferred translations - -For some strings we might not want to provide a translation right away. This -could be the case of running napari in scripts, where providing the original -english error messages might provide a better experience for users and -developers. - -For these case, all the `trans._*` methods provide an extra parameter -`deferred`. When used and set to `True`, the methods will return an instance -of a `TranslationString` which provides two methods, `TranslationString.value()` -and `TranslationString.translation()`. The former provides the original -untranslated string and the later provides the translated string. -Additionally, the `string` representation of this object will default to use -the original string. - -With this, we can also provide the correct translations when using the napari -application and displaying messages on the notifications manager in the -language selected by the users. - -## Additional arguments inside strings - -Since `f-strings` do not work with localizable strings, we loose their -convenience and have to use `str.format`. However, when using deferred -translations, we need to be able to use any variables the original string -needs to be able to render itself. To handle this, the `trans` helpers -provide the ability to receive any extra keyword arguments which will be -used for rendering the deferred strings on demand. - -An example of how this works with Spanish and deferred string yields: - -```python -from napari.utils.translations import trans - -deferred_string = trans._('Hello {word}', deferred=True, word='world!') - -str(deferred_string) == 'Hello world!' # True -deferred_string.value() == 'Hello world!' # True -deferred_string.translation() == '¡Hola mundo!' # True -``` - -An example of how this works for non-deferred string yields: - -```python -from napari.utils.translations import trans - -normal_string = trans._('Hello {word}', word='world!') -normal_string == '¡Hola mundo!' # True -``` - -## Contributing translations - -To be able to provide translations for different languages, the napari team -chose to use the `Crowdin` which provides a simple web interface where the -localizable strings can be translated one by one with the help of volunteers -and the napari user community. - -To start translating, please visit the [Crowdin project page](https://crowdin.com/project/napari). diff --git a/docs/developers/index.md b/docs/developers/index.md index 176ef77a8..b613c2331 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -19,7 +19,6 @@ Resources for contributors - [Contributing guide](napari-contributing) - [Development installation](dev-installation) - [Testing](napari-testing) - - [Translations](napari-translations) - [Performance](performance) - [Profiling](napari-profiling) - [Benchmarks](napari-benchmarks) From 62c7bf1e880461c6d9142a1c523ac28ad5b255ed Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Sat, 25 Jul 2026 10:08:10 +0200 Subject: [PATCH 2/5] Remove more mentions of translation from developer guides --- docs/developers/contributing/index.md | 8 -------- docs/developers/coredev/maintenance.md | 26 -------------------------- 2 files changed, 34 deletions(-) diff --git a/docs/developers/contributing/index.md b/docs/developers/contributing/index.md index 5ba7b626b..0041c9115 100644 --- a/docs/developers/contributing/index.md +++ b/docs/developers/contributing/index.md @@ -128,14 +128,6 @@ QtDeleteButton { } ``` -#### Translations - -Starting with version 0.4.7 offers the possibility of installing language packs, -enabling the user interface to be displayed in different languages. This means that all -user interface strings need to use the {func}`~napari.utils.translations.trans` helper -function. -See the [translations](translations) guide for more. - ### API If you are changing an existing API or adding a new one, make sure you update diff --git a/docs/developers/coredev/maintenance.md b/docs/developers/coredev/maintenance.md index c079e0de4..fc5be90df 100644 --- a/docs/developers/coredev/maintenance.md +++ b/docs/developers/coredev/maintenance.md @@ -65,29 +65,3 @@ Fill the form: To validate if the token is working, you can run the "Upgrade test constraints" workflow manually. Ensure that there will be some packages to update. -## Update translation strings - -Currently, translations are unmaintained, but this may change in the future as napari matures. - -As new code is included in the codebase, some of the strings that need to be translated might -not yet be using the `trans` methods. To help keep the codebase up to date in terms -of translations we added a test script that -[runs daily on CI](https://github.com/napari/napari/actions/workflows/test_translations.yml) -and can be also run locally to ensure that a release includes the most up to date translatable -strings. - -The test script is available on the `/tools/validate_strings.py` file and it relies on an additional -file `/tools/strings_list.py` to include strings to skip safely from translation. - -The test checks: - -1. **Untranslated strings**: not using the `trans` methods. -1. **Outdated skip strings**: should no longer be included in the `/tools/strings_list.py` file. -1. **Translation usage errors**: where translation strings may be missing interpolation variables. - -You can execute tests locally from the repository root, and follow the instructions printed -on the `stdout` if any test fails. - -```bash -pytest tools/ --tb=short -``` From 8eb931e3c406c2259d5aa4343160bc932f11064b Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Sat, 25 Jul 2026 10:10:59 +0200 Subject: [PATCH 3/5] Remove missing translations auto-issue --- .github/missing_translations.md | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 .github/missing_translations.md diff --git a/.github/missing_translations.md b/.github/missing_translations.md deleted file mode 100644 index d84fc8864..000000000 --- a/.github/missing_translations.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: [Automatic issue] Missing `_.trans()`. -labels: "good first issue" ---- - -It looks like one of our test cron detected missing translations. -You can see the latest output [here](https://github.com/napari/napari/actions/workflows/test_translations.yml). -There are likely new strings to either ignore, or to internationalise. - -You can also Update the cron script to update this issue with better information as well. - -Note that this issue will be automatically updated if kept open, or a new one will be created when necessary, if no open -issue is found and new `_.trans` call are missing. From 039de44d8a22a68770ad8c16340e66308e983d93 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 25 Jul 2026 08:18:01 +0000 Subject: [PATCH 4/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/developers/coredev/maintenance.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/developers/coredev/maintenance.md b/docs/developers/coredev/maintenance.md index fc5be90df..a6605c110 100644 --- a/docs/developers/coredev/maintenance.md +++ b/docs/developers/coredev/maintenance.md @@ -64,4 +64,3 @@ Fill the form: 12. Paste a new token to the value field To validate if the token is working, you can run the "Upgrade test constraints" workflow manually. Ensure that there will be some packages to update. - From 3eb35346fe2640e8caaba5466c591e39f574ccd1 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sat, 25 Jul 2026 10:31:59 +0200 Subject: [PATCH 5/5] remove translations from toc --- docs/_toc.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/_toc.yml b/docs/_toc.yml index b451580b8..08050b04b 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -203,7 +203,6 @@ subtrees: - file: developers/contributing/ai - file: developers/contributing/dev_install - file: developers/contributing/testing - - file: developers/contributing/translations - file: developers/contributing/performance/index subtrees: - entries: