━━━━━━━━━━━ c o d e c h u  ·  i 1 8 n ━━━━━━━━━━━

   en   Hello, Ada!     1 file        5 files
   tr   Merhaba Ada!    1 dosya       5 dosya
   ar   مرحبا Ada!      1 ملف         5 ملفات
   zh   你好, Ada!       1 个文件      5 个文件
   pl   Cześć Ada!      1 plik        5 plików

━━━ translate · negotiate · pluralize · RTL ━━━

Internationalization helpers on top of stdlib gettext.

codechu-i18n

Locale negotiation (RFC 4647), CLDR-derived plural rules, RTL detection, ICU-style message formatting, and a lazy Translator that defers .mo loading until first use. Pure stdlib — this library does not ship catalogs; that's the consuming app's job.

Install

pip install codechu-i18n

Python 3.10+. Zero third-party dependencies.

Quick example

from codechu_i18n import Translator, negotiate_locale, is_rtl, plural_form

# Pick a locale from what the user wants vs what you have.
locale = negotiate_locale(["fr", "tr"], ["tr-TR", "en-US", "de-DE"])
# → "tr-TR"

t = Translator("myapp", "locale", languages=[locale], fallback="en")
t.gettext("Hello")                             # "Merhaba"
t.ngettext("{n} file", "{n} files", 3)         # "3 dosya"
t.format("Hello {name}!", name="Ada")          # "Merhaba Ada!"

is_rtl("ar")            # True   — Arabic, Hebrew, Persian, Urdu, …
plural_form("pl", 5)    # 2 (many) — Polish three-form
plural_form("tr", 5)    # 0       — Turkish has no plural distinction

What you get

• Translator — lazy gettext wrapper with gettext, ngettext, pgettext, npgettext, and ICU-style format(template, **kwargs).
• negotiate_locale(requested, available) — RFC 4647 best-match lookup with fallback.
• detect_locale(env) — LC_ALL > LC_MESSAGES > LANG > LANGUAGE cascade. The caller supplies the env dict (no implicit os.environ read).
• is_rtl(locale) — Arabic, Hebrew, Persian, Urdu, Pashto, and the other right-to-left scripts.
• plural_form(locale, n) — CLDR plural category index; handles Slavic three-form, Polish, Arabic six-form, Welsh, French zero-as-one, Asian no-plural.
• lazy_gettext(msg) — module-level strings that resolve at render time, so locale switches take effect without re-imports.

This package is a thin layer over gettext. It does not ship .po / .mo catalogs — that's the consuming application's job. See the Codechu library i18n policy for the rationale.

Read more

• API reference — every public symbol with full signatures and edge-case tables.
• Changelog

Family

Library	Purpose
codechu-fmt	Human-readable sizes, durations, rates
codechu-cli	CLI primitives — colors, progress, prompts
codechu-config	Schema-driven config — atomic save, migrations
codechu-log	Structured logging — context, JSON, rotation
codechu-color	Color palettes, WCAG contrast, color-blind variants

Full ecosystem: github.com/codechu.

Credits

• Plural rules from CLDR (Unicode Common Locale Data Repository).
• Locale negotiation per RFC 4647.
• Built on stdlib gettext.

License

MIT — see LICENSE.

Part of Codechu.