Internationalization (i18n)

This guide explains how to add or update a language in NetNeighbor.

NetNeighbor uses GNU gettext catalogs under locale/<lang>/LC_MESSAGES/.

Current status

Source language: English strings in code wrapped with _().

Language	Code	Catalog
French	fr	locale/fr/LC_MESSAGES/netneighbor.po — partial (~150 untranslated strings)
Italian	it	locale/it/LC_MESSAGES/netneighbor.po — ready for translation
Spanish	es	locale/es/LC_MESSAGES/netneighbor.po — ready for translation
German	de	locale/de/LC_MESSAGES/netneighbor.po — ready for translation
Dutch	nl	locale/nl/LC_MESSAGES/netneighbor.po — ready for translation
Traditional Chinese (Taiwan)	zh_TW	locale/zh_TW/LC_MESSAGES/netneighbor.po — ready for translation
Simplified Chinese	zh_CN	locale/zh_CN/LC_MESSAGES/netneighbor.po — ready for translation
Japanese	ja	locale/ja/LC_MESSAGES/netneighbor.po — ready for translation

Prerequisites

• gettext tools installed (xgettext, msgmerge, msgfmt)
• Python environment ready to run main.py

On Debian/Ubuntu/Mint:

sudo apt update
sudo apt install -y gettext

1) Add or update translatable strings template

From repo root, generate a POT file from Python sources:

xgettext --from-code=UTF-8 -k_ -o locale/netneighbor.pot $(rg --files -g "*.py")

If you prefer, keep this command in a script later (for reproducible release flow).

2) Create a new language catalog

Example for Spanish (es):

mkdir -p locale/es/LC_MESSAGES
msginit --locale=es --input=locale/netneighbor.pot --output-file=locale/es/LC_MESSAGES/netneighbor.po

For an existing language, skip msginit and go to the merge step.

3) Merge new strings into existing catalogs

When code changed and new UI strings were added:

msgmerge --update locale/fr/LC_MESSAGES/netneighbor.po locale/netneighbor.pot
msgmerge --update locale/es/LC_MESSAGES/netneighbor.po locale/netneighbor.pot

4) Translate .po entries

Edit msgstr values in:

• locale/<lang>/LC_MESSAGES/netneighbor.po

Tips:

• Keep placeholders and punctuation intact.
• Keep menu labels short and consistent.
• Reuse existing terms for UI consistency (for example: Display, Arrange, Tools concepts).

5) Compile .mo files

Compile all languages after edits:

for lang in fr it es de nl zh_TW zh_CN ja; do
  msgfmt locale/$lang/LC_MESSAGES/netneighbor.po -o locale/$lang/LC_MESSAGES/netneighbor.mo
done

Or individually:

msgfmt locale/fr/LC_MESSAGES/netneighbor.po -o locale/fr/LC_MESSAGES/netneighbor.mo

6) Test in runtime

Run with a target locale:

LANG=fr_FR.UTF-8 python main.py
LANG=es_ES.UTF-8 python main.py

Check at least:

• View menu labels (Display, Arrange, sort labels)
• Tools menu (Notifications history)
• context menu labels (Location submenu with Auto, Device type)
• details dialog tabs and buttons

7) Commit checklist

• .po updated
• .mo compiled
• no obvious English leftovers on key screens
• docs updated if wording conventions changed