+
+
+
+
+ Documentation · Report Bug +
+ # generaltranslation-icu-messageformat-parser > ⚠️ **Experimental / Unstable** — This package is under active development and may be subject to breaking changes. -A pure-Python ICU MessageFormat parser with whitespace-preserving AST and string reconstruction. Python equivalent of [`@formatjs/icu-messageformat-parser`](https://www.npmjs.com/package/@formatjs/icu-messageformat-parser). - -Derived from [pyicumessageformat](https://github.com/SirStendec/pyicumessageformat) by Mike deBeaubien (MIT license). +A pure-Python ICU MessageFormat parser. Python equivalent of [`@formatjs/icu-messageformat-parser`](https://www.npmjs.com/package/@formatjs/icu-messageformat-parser). ## Installation @@ -12,8 +23,6 @@ Derived from [pyicumessageformat](https://github.com/SirStendec/pyicumessageform pip install generaltranslation-icu-messageformat-parser ``` -No dependencies. Pure Python. Requires Python 3.10+. - ## Quick Start ```python @@ -21,126 +30,5 @@ from generaltranslation_icu_messageformat_parser import Parser, print_ast parser = Parser() ast = parser.parse("{count, plural, one {# item} other {# items}}") -# [{'name': 'count', 'type': 'plural', 'offset': 0, 'options': {'one': [{'type': 'number', 'name': 'count', 'hash': True}, ' item'], 'other': [{'type': 'number', 'name': 'count', 'hash': True}, ' items']}}] -``` - -## API - -### `Parser(options=None)` - -Create a parser instance with optional configuration. - -**Options dict keys:** - -| Option | Type | Default | Description | -|---|---|---|---| -| `subnumeric_types` | `list[str]` | `['plural', 'selectordinal']` | Types that support `#` hash replacement | -| `submessage_types` | `list[str]` | `['plural', 'selectordinal', 'select']` | Types with sub-message branches | -| `maximum_depth` | `int` | `50` | Maximum nesting depth | -| `allow_tags` | `bool` | `False` | Enable XML-style `
+
+
+
+ Documentation · Report Bug +
+ # generaltranslation-intl-messageformat > ⚠️ **Experimental / Unstable** — This package is under active development and may be subject to breaking changes. ICU MessageFormat formatter with locale-aware plural and select rules. Python equivalent of [`intl-messageformat`](https://www.npmjs.com/package/intl-messageformat). -Uses [`generaltranslation-icu-messageformat-parser`](../generaltranslation-icu-messageformat-parser) for parsing and [Babel](https://babel.pocoo.org/) for CLDR plural rules. - ## Installation ```bash pip install generaltranslation-intl-messageformat ``` -Dependencies: `generaltranslation-icu-messageformat-parser`, `babel>=2.18.0`. Pure Python, no C extensions. - ## Quick Start ```python from generaltranslation_intl_messageformat import IntlMessageFormat -# Simple variable interpolation -mf = IntlMessageFormat("Hello, {name}!", "en") -mf.format({"name": "World"}) # "Hello, World!" - -# Plural with CLDR rules mf = IntlMessageFormat("{count, plural, one {# item} other {# items}}", "en") mf.format({"count": 1}) # "1 item" mf.format({"count": 5}) # "5 items" -mf.format({"count": 1000}) # "1,000 items" - -# Select -mf = IntlMessageFormat("{gender, select, male {He} female {She} other {They}} left.", "en") -mf.format({"gender": "female"}) # "She left." - -# Selectordinal -mf = IntlMessageFormat("{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}", "en") -mf.format({"n": 1}) # "1st" -mf.format({"n": 22}) # "22nd" -mf.format({"n": 3}) # "3rd" -mf.format({"n": 4}) # "4th" ``` - -## API - -### `IntlMessageFormat(pattern, locale="en")` - -Create a message formatter. - -**Args:** -- `pattern` (`str`): An ICU MessageFormat pattern string. -- `locale` (`str`): A BCP 47 locale tag. Defaults to `"en"`. Falls back to `"en"` if the locale is invalid. - -### `IntlMessageFormat.format(values=None)` - -Format the message with variable values. - -**Args:** -- `values` (`dict | None`): A dict mapping variable names to values. Values can be `str`, `int`, `float`, or any type convertible via `str()`. Missing variables resolve to empty string. - -**Returns:** `str` — The formatted message. - -### `IntlMessageFormat.pattern` - -**Type:** `str` — The original pattern string (read-only property). - -### `IntlMessageFormat.locale` - -**Type:** `babel.Locale` — The resolved Babel locale (read-only property). - -## Supported ICU Features - -### Simple variables -```python -IntlMessageFormat("Hello, {name}!", "en").format({"name": "World"}) -# "Hello, World!" -``` - -### Plural -Selects a branch based on CLDR plural rules for the locale. Supports `one`, `two`, `few`, `many`, `other`, and `zero` categories, plus exact matches with `=N`. - -```python -# English: one/other -IntlMessageFormat("{n, plural, one {# dog} other {# dogs}}", "en").format({"n": 1}) -# "1 dog" - -# Arabic: zero/one/two/few/many/other -IntlMessageFormat( - "{n, plural, zero {صفر} one {واحد} two {اثنان} few {# قليل} many {# كثير} other {# آخر}}", "ar" -).format({"n": 3}) -# "3 قليل" - -# Russian: one/few/many/other -IntlMessageFormat( - "{n, plural, one {# книга} few {# книги} many {# книг} other {# книг}}", "ru" -).format({"n": 21}) -# "21 книга" -``` - -### Exact match -```python -IntlMessageFormat( - "{n, plural, =0 {no items} =1 {one item} other {# items}}", "en" -).format({"n": 0}) -# "no items" -``` - -### Plural with offset -The `offset` value is subtracted before plural rule evaluation. The `#` hash displays the offset-adjusted value. - -```python -IntlMessageFormat( - "{guests, plural, offset:1 =0 {nobody} =1 {{host}} one {{host} and # other} other {{host} and # others}}", "en" -).format({"guests": 3, "host": "Alice"}) -# "Alice and 2 others" -``` - -### Selectordinal -Selects a branch based on CLDR ordinal plural rules. - -```python -IntlMessageFormat( - "{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}", "en" -).format({"n": 23}) -# "23rd" -``` - -### Select -Matches a string value to a branch key, falls back to `other`. - -```python -IntlMessageFormat( - "{type, select, cat {meow} dog {woof} other {???}}", "en" -).format({"type": "cat"}) -# "meow" -``` - -### Nested expressions -Plural inside select, select inside plural, variables inside branches — all work. - -```python -IntlMessageFormat( - "{gender, select, male {He has {n, plural, one {# item} other {# items}}} other {They have {n, plural, one {# item} other {# items}}}}", "en" -).format({"gender": "male", "n": 1}) -# "He has 1 item" -``` - -### Hash `#` replacement -Inside plural/selectordinal branches, `#` is replaced with the numeric value (locale-formatted with grouping separators). - -```python -IntlMessageFormat("{n, plural, other {# items}}", "en").format({"n": 1000}) -# "1,000 items" - -IntlMessageFormat("{n, plural, other {# Artikel}}", "de").format({"n": 1000}) -# "1.000 Artikel" -``` - -## Locale Support - -Uses Babel's CLDR data for plural rules, covering 100+ locales. Tested against `icu4py` (ICU4C bindings) for correctness across: - -- **English** (en) — one/other -- **French** (fr) — one/other (0 is "one") -- **German** (de) — one/other -- **Arabic** (ar) — zero/one/two/few/many/other -- **Russian** (ru) — one/few/many/other -- **Polish** (pl) — one/few/many/other -- **Japanese** (ja) — other only -- And all other locales supported by Babel/CLDR - -## Known Carve-outs - -- **Boolean values**: Python `True`/`False` are formatted as `"True"`/`"False"` (Python convention). ICU4C formats them as `1`/`0`. -- **Escape sequences**: `''` and `'{...}'` are unescaped during parsing (matching `@formatjs/icu-messageformat-parser` behavior). The formatted output contains the unescaped text. diff --git a/packages/generaltranslation-supported-locales/README.md b/packages/generaltranslation-supported-locales/README.md index 5bd735f..168de6e 100644 --- a/packages/generaltranslation-supported-locales/README.md +++ b/packages/generaltranslation-supported-locales/README.md @@ -1,3 +1,24 @@ +
+
+
+
+ Documentation · Report Bug +
+ # generaltranslation-supported-locales > ⚠️ **Experimental / Unstable** — This package is under active development and may be subject to breaking changes. + +Locale validation and metadata for General Translation's Python packages. + +## Installation + +```bash +pip install generaltranslation-supported-locales +``` diff --git a/packages/generaltranslation/README.md b/packages/generaltranslation/README.md index 977ae05..f2fd845 100644 --- a/packages/generaltranslation/README.md +++ b/packages/generaltranslation/README.md @@ -1,3 +1,26 @@ +
+
+
+
+ Documentation · Report Bug +
+ # generaltranslation > ⚠️ **Experimental / Unstable** — This package is under active development and may be subject to breaking changes. + +Core Python language toolkit for General Translation. + +## Installation + +```bash +pip install generaltranslation +``` + +See the [full documentation](https://generaltranslation.com/docs/python) for guides and API reference. diff --git a/packages/gt-fastapi/README.md b/packages/gt-fastapi/README.md index 8314524..83fcbf2 100644 --- a/packages/gt-fastapi/README.md +++ b/packages/gt-fastapi/README.md @@ -1,3 +1,40 @@ +
+
+
+
+ Documentation · Report Bug +
+ # gt-fastapi > ⚠️ **Experimental / Unstable** — This package is under active development and may be subject to breaking changes. + +Automatic i18n for FastAPI. + +## Installation + +```bash +pip install gt-fastapi +``` + +## Quick Start + +```python +from fastapi import FastAPI +from gt_fastapi import initialize_gt, t + +app = FastAPI() +initialize_gt(app, default_locale="en", locales=["en", "es", "fr"]) + +@app.get("/") +def hello(): + return {"message": t("Hello, world!")} +``` + +See the [full documentation](https://generaltranslation.com/docs/python) for guides and API reference. diff --git a/packages/gt-flask/README.md b/packages/gt-flask/README.md index f3d708e..85535f6 100644 --- a/packages/gt-flask/README.md +++ b/packages/gt-flask/README.md @@ -1,3 +1,40 @@ +
+
+
+
+ Documentation · Report Bug +
+ # gt-flask > ⚠️ **Experimental / Unstable** — This package is under active development and may be subject to breaking changes. + +Automatic i18n for Flask. + +## Installation + +```bash +pip install gt-flask +``` + +## Quick Start + +```python +from flask import Flask +from gt_flask import initialize_gt, t + +app = Flask(__name__) +initialize_gt(app, default_locale="en", locales=["en", "es", "fr"]) + +@app.route("/") +def hello(): + return t("Hello, world!") +``` + +See the [full documentation](https://generaltranslation.com/docs/python) for guides and API reference. diff --git a/packages/gt-i18n/README.md b/packages/gt-i18n/README.md index 9ccb666..5cc52ba 100644 --- a/packages/gt-i18n/README.md +++ b/packages/gt-i18n/README.md @@ -1,3 +1,36 @@ +
+
+
+
+ Documentation · Report Bug +
+ # gt-i18n > ⚠️ **Experimental / Unstable** — This package is under active development and may be subject to breaking changes. + +Core Python i18n library for General Translation. + +## Installation + +```bash +pip install gt-i18n +``` + +## Quick Start + +```python +from gt_i18n import t, init_gt + +init_gt(default_locale="en", locales=["en", "es", "fr"]) + +print(t("Hello, world!")) +``` + +See the [full documentation](https://generaltranslation.com/docs/python) for guides and API reference.