One keyboard and mouse for a Mac and a Windows PC over the local network, in either direction.
"""Beamer's display language: gettext catalogues with British English as the source.
Every user-visible string is written in British English and wrapped where it is used:
``tr("Hide addresses")``, ``trn("{n} machine", "{n} machines", n).format(n=n)``, and
``trc("menu", "Open")`` where one English word needs two translations. A string defined at
import time (a module constant, a table of names) is marked with ``N_()`` and translated where it
is shown, with ``tr(CONSTANT)``, because the language is installed after imports and before the
first window. Names, addresses and anything else a person typed are never passed through ``tr()``:
they go into a template as a ``{field}`` instead, so a machine called "Home" is never translated.
Catalogues are ``locales/<code>.po`` beside VERSION, read with the standard library only. The
English catalogue is the template (``locales/beamer.pot``) that ``tools/i18n_extract.py`` writes;
a language is one more ``.po`` file and one line in ``LANGUAGES``. The US spelling of English
is applied to these authored templates before typed values are interpolated.
"""
from __future__ import annotations
import ast
import ctypes
import gettext as _gettext
import io
import os
import re
import struct
import sys
from pathlib import Path
from core.locale import americanise
# Code -> the language's own name for itself, shown in the Language choice whatever the current
# language is, so a person who cannot read the current one can still find theirs.
LANGUAGES = {
"en": "English",
"it": "Italiano",
}
# Not a language: every string bracketed and a third longer, so a test can find text that never
# went through tr() and see where longer languages run out of room. Only BEAMER_LANGUAGE sets it.
PSEUDO = "qps"
AUTOMATIC = "auto"
SOURCE = "en"
_translations: _gettext.NullTranslations = _gettext.NullTranslations()
_language = SOURCE
def N_(message: str) -> str:
"""Mark a string for the catalogue without translating it yet."""
return message
def tr(message: str) -> str:
return americanise(_translations.gettext(message))
def matches_translation(text: str, *templates: str) -> bool:
"""Recognise a formatted translated template without interpreting its field values."""
for template in templates:
parts = re.split(r"\{[^{}]+\}", tr(template))
if re.fullmatch(".*?".join(re.escape(part) for part in parts), text, re.DOTALL):
return True
return False
def trn(singular: str, plural: str, n: int) -> str:
return americanise(_translations.ngettext(singular, plural, n))
def trc(context: str, message: str) -> str:
return americanise(_translations.pgettext(context, message))
def joined(items) -> str:
"""Names as one phrase in the current language: "Mac", "Mac and PC", "Mac, PC and Laptop"."""
items = [str(item) for item in items]
if len(items) < 2:
return "".join(items)
# Translators: the separator between all but the last two names in a list, "Mac, PC and Laptop".
head = trc("list", ", ").join(items[:-1])
# Translators: the last two names of a list; {first} may itself be several names.
return trc("list", "{first} and {last}").format(first=head, last=items[-1])
def language() -> str:
"""The installed language's code."""
return _language
def locales_dir() -> Path:
# py2app sets RESOURCEPATH and PyInstaller _MEIPASS; from source and in the Flatpak, the
# folder sits beside core/, as VERSION does.
for root in (os.environ.get("RESOURCEPATH"), getattr(sys, "_MEIPASS", None)):
if root and (Path(root) / "locales").is_dir():
return Path(root) / "locales"
# __spec__.origin, not __file__: py2app's detect_dunder_file recipe copies the whole package of
# any module naming __file__ into the bundle as loose source, core's tests with it, and those
# import mac_app, which then copies the build folder into itself (14-10-2026).
return Path(__spec__.origin).resolve().parent.parent / "locales"
def _unquote(token: str) -> str:
# A .po string is a C string literal; for the escapes .po files use, \" \\ \n \t, that is
# also a Python one.
return ast.literal_eval(token)
def parse_po(text: str) -> list[dict]:
"""Every entry of a .po file, the header included, as {msgctxt, msgid, msgid_plural, msgstr: [..], flags, comments}."""
entries, entry, field = [], None, None
def finish():
if entry is not None and "msgid" in entry:
entries.append(entry)
for raw in text.splitlines():
line = raw.strip()
if not line:
continue
if line.startswith("#"):
if entry is not None and "msgid" in entry:
finish()
entry = None
entry = entry or {"msgstr": {}, "flags": set(), "comments": []}
if line.startswith("#,"):
entry["flags"].update(flag.strip() for flag in line[2:].split(","))
else:
entry["comments"].append(raw)
continue
if line.startswith('"'):
value = _unquote(line)
if field[0] == "msgstr":
entry["msgstr"][field[1]] += value
else:
entry[field[0]] += value
continue
keyword, _space, rest = line.partition(" ")
if keyword in ("msgctxt", "msgid") and entry is not None and "msgid" in entry:
finish()
entry = None
entry = entry or {"msgstr": {}, "flags": set(), "comments": []}
if keyword.startswith("msgstr"):
index = int(keyword[7:-1]) if keyword.startswith("msgstr[") else 0
entry["msgstr"][index] = _unquote(rest)
field = ("msgstr", index)
elif keyword in ("msgctxt", "msgid", "msgid_plural"):
entry[keyword] = _unquote(rest)
field = (keyword, None)
else:
raise ValueError(f"unreadable .po line: {raw!r}")
finish()
for item in entries:
item["msgstr"] = [item["msgstr"][i] for i in sorted(item["msgstr"])]
return entries
def _mo_bytes(entries: list[dict]) -> bytes:
# The .mo layout from the GNU gettext manual, so the standard library's GNUTranslations reads
# plural forms from the catalogue's own Plural-Forms header. Building it in memory keeps the
# .po the only file there is: nothing to compile, nothing to fall out of step.
pairs = {}
for entry in entries:
if "fuzzy" in entry["flags"] or (entry["msgid"] and not any(entry["msgstr"])):
continue
key = entry["msgid"]
if "msgid_plural" in entry:
key += "\0" + entry["msgid_plural"]
if "msgctxt" in entry:
key = entry["msgctxt"] + "\x04" + key
pairs[key.encode()] = "\0".join(entry["msgstr"]).encode()
keys = sorted(pairs)
ids = strs = b""
offsets = []
for key in keys:
offsets.append((len(key), len(ids), len(pairs[key]), len(strs)))
ids += key + b"\0"
strs += pairs[key] + b"\0"
start = 7 * 4 + 16 * len(keys)
table = []
for id_len, id_at, str_len, str_at in offsets:
table.append((id_len, start + id_at, str_len, start + len(ids) + str_at))
head = struct.pack("Iiiiiii", 0x950412DE, 0, len(keys), 7 * 4, 7 * 4 + 8 * len(keys), 0, 0)
return (head + b"".join(struct.pack("ii", a, b) for a, b, _c, _d in table)
+ b"".join(struct.pack("ii", c, d) for _a, _b, c, d in table) + ids + strs)
class _Pseudo(_gettext.NullTranslations):
_ACCENTS = str.maketrans("aeiouAEIOU", "àéîõüÀÉÎÕÜ")
def _wrap(self, text: str) -> str:
parts = re.split(r"(\{[^{}]*\})", text)
body = "".join(part if part.startswith("{") else part.translate(self._ACCENTS) for part in parts)
return "⟦" + body + "·" * (len(text) // 3) + "⟧"
def gettext(self, message):
return self._wrap(message)
def ngettext(self, singular, plural, n):
return self._wrap(singular if n == 1 else plural)
def pgettext(self, context, message):
return self._wrap(message)
def load(code: str) -> _gettext.NullTranslations:
if code == SOURCE:
return _gettext.NullTranslations()
if code == PSEUDO:
return _Pseudo()
path = locales_dir() / f"{code}.po"
entries = parse_po(path.read_text(encoding="utf-8"))
return _gettext.GNUTranslations(io.BytesIO(_mo_bytes(entries)))
def _mac_languages() -> list[str]:
from Foundation import NSLocale
return [str(code) for code in NSLocale.preferredLanguages() or ()]
def _windows_languages() -> list[str]:
count, size = ctypes.c_ulong(), ctypes.c_ulong()
get = ctypes.windll.kernel32.GetUserPreferredUILanguages
if not get(8, ctypes.byref(count), None, ctypes.byref(size)): # MUI_LANGUAGE_NAME
return []
buffer = ctypes.create_unicode_buffer(size.value)
if not get(8, ctypes.byref(count), buffer, ctypes.byref(size)):
return []
return [code for code in buffer[:size.value].split("\0") if code]
def _linux_languages() -> list[str]:
# gettext's own order: LANGUAGE is a list and wins, unless the locale itself is C/POSIX.
for key in ("LC_ALL", "LC_MESSAGES", "LANG"):
value = os.environ.get(key)
if value:
if value.split(".")[0] in ("C", "POSIX"):
return []
listed = os.environ.get("LANGUAGE")
return (listed.split(":") if listed else []) + [value]
return []
def system_languages() -> list[str]:
"""The person's preferred languages, most preferred first, as the operating system lists them."""
try:
if sys.platform == "darwin":
return _mac_languages()
if sys.platform == "win32":
return _windows_languages()
return _linux_languages()
except (AttributeError, OSError, ImportError, ValueError):
return []
def _base(code: str) -> str:
return code.replace("-", "_").split("_")[0].split(".")[0].split("@")[0].lower()
def resolve(choice: str | None, preferred: list[str] | None = None) -> str:
"""The language to show for a setting of `choice`: the code itself, or for Automatic the first
of the system's preferred languages Beamer has, as macOS picks an app's language."""
forced = os.environ.get("BEAMER_LANGUAGE")
if forced in LANGUAGES or forced == PSEUDO:
return forced
if choice in LANGUAGES:
return choice
for code in system_languages() if preferred is None else preferred:
base = _base(code)
if base in LANGUAGES:
return base
return SOURCE
def install(choice: str | None = AUTOMATIC) -> str:
"""Install the language for `choice` ("auto" or a code) and return its code. A catalogue that
cannot be read leaves the app in English rather than stopping it starting."""
global _translations, _language
code = resolve(choice)
try:
_translations = load(code)
except (OSError, ValueError, SyntaxError):
code, _translations = SOURCE, _gettext.NullTranslations()
_language = code
return code
def is_source() -> bool:
return _language == SOURCE