i18nice

https://pypi.org/project/i18nice/
Admin
i18nice is a Python internationalization library that provides i18n functionality with support for...
Tokens:3,675
Snippets:55
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install i18nice

Source: https://pypi.org/project/i18nice/0.16.0

Standard installation command for the library.

```bash
pip install i18nice
```

--------------------------------

### Install i18nice

Source: https://pypi.org/project/i18nice

Standard installation via pip, with an optional variant for YAML support.

```bash
pip install i18nice
```

```bash
pip install i18nice[YAML]
```

--------------------------------

### Install i18nice with YAML support

Source: https://pypi.org/project/i18nice/0.16.0

Installation command including the YAML extra for translation file support.

```bash
pip install i18nice[YAML]
```

--------------------------------

### Setup Development Environment

Source: https://pypi.org/project/i18nice/0.16.0

Use the dev-helper script to set up the virtual environment, run tests, and perform code quality checks for the project.

```bash
python dev-helper.py
```

--------------------------------

### Install Git Pre-commit Hook

Source: https://pypi.org/project/i18nice/0.16.0

Install the git pre-commit hook using the dev-helper script to automate checks before committing code.

```bash
python dev-helper.py install
```

--------------------------------

### Translation File Formats

Source: https://pypi.org/project/i18nice

Example structures for YAML and JSON translation files.

```yaml
en:
  hi: Hello world !
```

```json
{
  "en": {
    "hi": "Hello world !"
  }
}
```

--------------------------------

### JSON Translation File Structure

Source: https://pypi.org/project/i18nice

Example of a JSON file structure for translations. This can be used as a base file for translations in Python sub-projects.

```json
{
  "foo": "FooBar"
}
```

--------------------------------

### Load Translations from Different Directory Structure

Source: https://pypi.org/project/i18nice

Configure i18nice to load translations from a nested directory structure by setting `use_locale_dirs` to True. This example assumes a 'locales' directory with locale-specific subdirectories.

```python
import i18n

i18n.load_path.append("locales")
i18n.set("file_format", "yml")
i18n.set("filename_format", "{namespace}.{format}")
i18n.set("skip_locale_root_data", True)
i18n.set("use_locale_dirs", True)

print(i18n.t("common.text1", locale="en-US"))
print(i18n.t("gui.page1.title", locale="en-US"))
```

--------------------------------

### Run Tests

Source: https://pypi.org/project/i18nice/0.16.0

Execute all project tests using the dev-helper script.

```bash
python dev-helper.py run-tests
```

--------------------------------

### Loading Translation Files

Source: https://pypi.org/project/i18nice

Configuring the translation path and retrieving keys from loaded files.

```python
import i18n
i18n.load_path.append('/path/to/translations')
i18n.t('foo.hi') # Hello world !
```

--------------------------------

### Basic Translation Usage

Source: https://pypi.org/project/i18nice

Demonstrates adding a translation manually and retrieving it using the translation key.

```python
import i18n
i18n.add_translation('foo', 'bar')
i18n.t('foo') # bar
```

--------------------------------

### Run Code Quality Checks

Source: https://pypi.org/project/i18nice/0.16.0

Perform code quality checks on the project using the dev-helper script.

```bash
python dev-helper.py run-checks
```

--------------------------------

### Load translations from directory structures

Source: https://pypi.org/project/i18nice/0.16.0

Enable use_locale_dirs to support nested directory structures for translation files.

```text
locales
├── en-US
│   ├── common.yml
│   └── gui
│       ├── page1.yml
│       └── page2.yml
└── fr-FR
    ├── common.yml
    └── gui
        ├── page1.yml
        └── page2.yml
```

```python
import i18n

i18n.load_path.append("locales")
i18n.set("file_format", "yml")
i18n.set("filename_format", "{namespace}.{format}")
i18n.set("skip_locale_root_data", True)
i18n.set("use_locale_dirs", True)

print(i18n.t("common.text1", locale="en-US"))
print(i18n.t("gui.page1.title", locale="en-US"))
```

--------------------------------

### Custom YAML Loader

Source: https://pypi.org/project/i18nice

Registering a custom loader to enable full YAML functionality.

```python
class MyLoader(i18n.loaders.YamlLoader):
    loader = yaml.FullLoader

i18n.register_loader(MyLoader, ["yml", "yaml"])
```

--------------------------------

### Add Translation with Placeholder

Source: https://pypi.org/project/i18nice

Use this to add translations with dynamic placeholders. Placeholders are inserted using `%{placeholder_name}`.

```python
i18n.add_translation('hi', 'Hello %{name} !')
i18n.t('hi', name='Bob') # Hello Bob !
```

--------------------------------

### Configure Filename Format

Source: https://pypi.org/project/i18nice

Modifying the configuration to remove the namespace from the filename format.

```python
i18n.set('filename_format', '{locale}.{format}')
```

--------------------------------

### Static References in Translations

Source: https://pypi.org/project/i18nice

Utilize static references to reuse translation values by prefixing a key with a namespace delimiter. Keys are searched from top to bottom.

```json
{
  "en": {
    "progname": "Program Name",
    "welcome": "Welcome to %{.progname}!"
  }
}
```

```json
{
  "en": {
    "interface": {
      "progname": "Program Name",
      "ref": "%{.progname} and %{.interface.progname} refer to the same value"
    }
  }
}
```

--------------------------------

### Set Fallback Locale

Source: https://pypi.org/project/i18nice

Configure a fallback locale to be used when a translation key is not found in the default locale. Setting locale and fallback to the same value results in fallback being None.

```python
i18n.set('locale', 'jp')
i18n.set('fallback', 'en')
i18n.add_translation('foo', 'bar', locale='en')
i18n.t('foo') # bar
```

--------------------------------

### Use translation lists

Source: https://pypi.org/project/i18nice/0.16.0

Define and access lists of translations, including support for pluralization and lazy evaluation.

```yaml
# translations.en.yml
en:
  days:
    - Monday
    - Tuesday
    - Wednesday
    ...
```

```python
# translate.py
from datetime import date
import i18n

i18n.load_path.append(".")
# will print current day
print(i18n.t("translations.days")[date.today().weekday()])
```

```yaml
days:
  - one: Monday
    many: Mondays
  ...
```

```python
# ({'one': 'Monday', 'many': 'Mondays'}, {'one': 'Tuesday', 'many': 'Tuesdays'}, ...)
print(i18n.t("translations.days", count=3))
# ('Mondays', 'Tuesdays', 'Wednesdays')
print(i18n.t("translations.days", count=3)[:])
```

--------------------------------

### Pluralization in Lists

Source: https://pypi.org/project/i18nice

Shows how to use pluralization within lists of translations. The `_list=True` argument can be passed to `t` for type checking purposes.

```yaml
days:
  - one: Monday
    many: Mondays
  ...
```

```python
# ({'one': 'Monday', 'many': 'Mondays'}, {'one': 'Tuesday', 'many': 'Tuesdays'}, ...)
print(i18n.t("translations.days", count=3))
# ('Mondays', 'Tuesdays', 'Wednesdays')
print(i18n.t("translations.days", count=3)[:])
```

--------------------------------

### Configure Custom Placeholder Handler in i18n

Source: https://pypi.org/project/i18nice

Set a custom function to handle missing placeholders during translation. This function will be called when a placeholder in the translation string is not provided with a value. Requires the 'logging' and 'i18n' libraries.

```python
import logging, i18n

def handler(key, locale, text, name):
    logging.warning(f"Missing placeholder {name!r} while translating {key!r} to {locale!r} (in {text!r})")
    return "undefined"

i18n.set("on_missing_placeholder", handler)
i18n.add_translation("am", "Amount is %{amount}")
print(i18n.t("am"))
# output:
# WARNING:root:Missing placeholder 'amount' while translating 'am' to 'en' (in 'Amount is %{amount}')
# Amount is undefined
```

--------------------------------

### Configure Skipping Locale Root Data

Source: https://pypi.org/project/i18nice

Enable `skip_locale_root_data` to ignore the root locale element (e.g., 'en') from JSON translation files when loading.

```python
i18n.set('skip_locale_root_data', True)
```

--------------------------------

### Use Lists of Translations

Source: https://pypi.org/project/i18nice

Demonstrates how to use lists of translations. The `t` function returns a `LazyTranslationTuple` which can be fully processed using slicing `[:]`.

```yaml
# translations.en.yml
en:
  days:
    - Monday
    - Tuesday
    - Wednesday
```

```python
# translate.py
from datetime import date
import i18n

i18n.load_path.append(".")
# will print current day
print(i18n.t("translations.days")[date.today().weekday()])
```

--------------------------------

### Configure Custom Placeholder Handler in i18n

Source: https://pypi.org/project/i18nice/0.16.0

Set a custom function to handle missing placeholders during translation. This function will be called when a placeholder in the translation string is not provided.

```python
import logging, i18n

def handler(key, locale, text, name):
    logging.warning(f"Missing placeholder {name!r} while translating {key!r} to {locale!r} (in {text!r})")
    return "undefined"

i18n.set("on_missing_placeholder", handler)
i18n.add_translation("am", "Amount is %{amount}")
print(i18n.t("am"))
```

--------------------------------

### Add Translation with Pluralization

Source: https://pypi.org/project/i18nice

Define translations that support pluralization by providing a dictionary with 'one' and 'many' keys. 'zero' and 'few' keys can also be specified.

```python
i18n.add_translation('mail_number', {
    'zero': 'You do not have any mail.',
    'one': 'You have a new mail.',
    'few': 'You only have %{count} mails.',
    'many': 'You have %{count} new mails.'
})
i18n.t('mail_number', count=0) # You do not have any mail.
i18n.t('mail_number', count=1) # You have a new mail.
i18n.t('mail_number', count=3) # You only have 3 new mails.
i18n.t('mail_number', count=12) # You have 12 new mails.
```

--------------------------------

### Skip locale root in JSON

Source: https://pypi.org/project/i18nice/0.16.0

Configure the library to ignore the top-level locale key in translation files.

```json
{
  "foo": "FooBar"
}
```

```python
i18n.set('skip_locale_root_data', True)
```

--------------------------------

### Implement Custom Pluralization Function in i18n

Source: https://pypi.org/project/i18nice

Define and register a custom function for handling plural forms in translations, particularly useful for languages with complex pluralization rules. The function receives arguments and determines the correct plural form based on the 'count'.

```python
i18n.set("locale", "uk")
i18n.add_translation("days", "%{count} %{p(день|дні|днів)}")

def determine_plural_form(*args, count, **_):
    count = abs(count)
    if count % 10 >= 5 or count % 10 == 0 or (count % 100) in range(11, 20):
        return args[2]
    elif count % 10 == 1:
        return args[0]
    return args[1]

i18n.add_function("p", determine_plural_form, "uk")
i18n.t("days", count=1) # 1 день
i18n.t("days", count=2) # 2 дні
i18n.t("days", count=5) # 5 днів
```
Tokens:
Raw