Noctalia i18n Core

简体中文

Noctalia i18n Core is a read-only Python client for project progress, current translations, and changes from Noctalia Translate. Storage, scheduling, delivery, and application policy belong to the caller.

Capabilities

• Read project details, translation context, and project-wide and per-locale progress.
• Read current translations as a complete catalog, exact-key results, or text-search results.
• Query missing translations and translations that need review in a selected locale.
• List dot-separated translation keys and filter them by hierarchy prefix.
• Read complete changes for selected keys in one locale.
• Lazily read the project-wide change stream with locale, time, and anchor boundaries.
• Read validated change pages with a durable cursor for resumable scans.
• Retry temporary connection, timeout, rate-limit, and server failures.
• Use a caller-owned requests.Session when connection policy must be configured by the application.

Project structure

noctalia_i18n_core/
├── client.py   # Website requests and response validation
└── models.py   # Normalized project and change values

Installation

uv add noctalia-i18n-core

Or with pip:

pip install noctalia-i18n-core

Usage

Create a client

from noctalia_i18n_core import NoctaliaClient

with NoctaliaClient("noctalia", timeout=30) as client:
    key = "settings.widgets.settings.scroll-repeat.label"
    value = client.translations(key, locales=("zh-Hans",))[key]["zh-Hans"]
    changes = client.changes(key, locale="zh-Hans")

    print(value)
    print(changes[0].occurred_at if changes else "No changes")

The client retries temporary failures and closes the session it creates. Pass a configured requests.Session when the application owns connection settings such as proxies or retry policy; caller-owned sessions are used without modification.

Project details and progress

project() makes one project request and returns the public name, description, translation context, and current progress. Project and locale progress use the integer percentage shown by the website. The review count identifies translations whose English source changed after that translation was last saved.

project = client.project()

print(project.name, project.key_count, project.language_count, project.progress)
for locale in project.locales:
    print(
        locale.code,
        locale.progress,
        locale.missing_count,
        locale.review_count,
    )

Current translations

translations() reads one or more exact keys in website-sized batches. Its key-first result preserves the requested key and locale order. A requested key remains present with an empty mapping when no selected locale has a value.

values = client.translations(
    "settings.widgets.settings.scroll-repeat.description",
    "settings.widgets.settings.scroll-repeat.label",
    locales=("zh-Hans", "en"),
)

catalog() makes one complete export request and returns {key: {locale: value}}. It is intended for callers that need every current translation.

catalog = client.catalog()
source_text = catalog["settings.widgets.settings.scroll-repeat.description"]["en"]

Text search

search_translations() searches the key and current value in search_locale, follows all result pages, and reads the requested result locales for the matching keys. If locales is omitted, the result contains only search_locale.

matches = client.search_translations(
    "确认",
    search_locale="zh-Hans",
    locales=("zh-Hans", "en"),
)

Missing translations and reviews

missing() returns source entries without a current translation in one locale. reviews() returns entries whose English source changed after the translation was last saved. Both results include the key, locale, current source, and translation page; reviews additionally include the previous source. Both queries accept query to filter their results.

missing = client.missing("fr", query="scroll")
reviews = client.reviews("fr")

for item in missing:
    print(item.key, item.source, item.translation_url)

for review in reviews:
    print(review.key, review.previous_source, review.source)

Translation keys

keys() makes one key-tree request and returns the complete key list. A prefix matches a complete dot-separated hierarchy rather than an arbitrary string prefix.

widget_keys = client.keys(prefix="settings.widgets")

Changes for selected keys

changes() reads the complete changes for one or more exact keys in one locale. The returned tuple is ordered from newest to oldest; multiple key results are merged in that order.

changes = client.changes(
    "settings.widgets.settings.scroll-repeat.description",
    locale="zh-Hans",
)
for change in changes:
    print(change.occurred_at, change.action, change.new_value)

Project change stream

iter_changes() lazily reads the project-wide change stream in the order supplied by the website. since and until are inclusive, timezone-aware boundaries and are normalized to UTC. locale restricts the stream to one locale.

from datetime import UTC, datetime

recent = client.iter_changes(
    locale="zh-Hans",
    since=datetime(2026, 8, 1, tzinfo=UTC),
)
for change in recent:
    print(change.key, change.action)

after is a website change ID. The client confirms the anchor before yielding a result and raises RuntimeError when it is absent. on_progress receives the completed page number and current total page count after each request.

change_pages() exposes the same stream as immutable ChangePage values. start_page selects a one-based page. cursor is an opaque resume position stored by the caller; the client discards that position and newer records before continuing with older pages.

page = next(client.change_pages(start_page=1))
print(page.number, page.total_pages, page.cursor)

API reference

NoctaliaClient

NoctaliaClient(project, *, timeout, session=None)

project is the website project identifier. timeout is a positive finite number of seconds applied to each attempt. By default, temporary connection, timeout, rate-limit, and server failures are retried three times with backoff. session may be a caller-owned requests.Session; its transport policy is preserved and the client does not close it.

translations() and changes() require at least one positional key. translations() returns requested keys even when their result is empty. changes() returns a tuple and requests each selected key from the website. iter_changes() never accepts keys and remains lazy until iteration begins.

Invalid arguments raise ValueError. Network failures that remain after retries and responses that do not match the website contract raise RuntimeError.

Project and Locale

Project contains public project details and progress aggregated from the current locale states:

Each Locale contains code, translation_count, missing_count, review_count, and the derived progress. Locales without any current translations remain present in the project result.

Missing and Review

Both models contain key, locale, source, and translation_url. Review additionally contains previous_source, which is None when no previous source text exists. This source difference is distinct from changes to the translation itself.

Change

Each change has the following fields:

ChangeAction is the literal type "added" | "modified" | "deleted". SOURCE_LOCALE is "en".

ChangePage

ChangePage contains number, total_pages, changes, and cursor. cursor corresponds to the final raw website record on the page, including a record that normalizes to no Change; callers should treat it only as an opaque resume value.

Performance reference

These reference measurements were taken from the public noctalia project in August 2026. They describe website requests without a local cache.

Latency, server load, and project growth affect these values. Exact queries and text searches do not download the complete catalog.

Development

Install the locked development environment:

uv sync --locked

Run formatting, linting, type checking, and tests:

uv run ruff format --check .
uv run ruff check .
uv run basedpyright
uv run python -m unittest discover -v

The default suite validates models, response parsing, and client behavior without accessing external services.

Run the live contract tests explicitly to verify every public operation against the current public projects on Noctalia Translate:

uv run python -m unittest tests.live -v

Build and inspect both distributions:

uv build --no-sources --clear
uvx twine check --strict dist/*

License

MIT