i18n_keyless_core library

Classes

ApiResult: One HTTP answer, already reduced to what the client needs. Never throws.
BundleManifest: manifest.json: the bundle without its dictionaries.
BundleNamespace: One namespace of the manifest: its cursor and the languages that have a file.
BundleSeed: The seed of one namespace: a dictionary and the cursor that goes with it.
HandleTranslateResult: What a HandleTranslate handler returns.
I18nKeylessApi: One shared request path for every API call, with the resilience a bare request lacks:
I18nKeylessBundle: The bundle handed to I18nKeylessConfig.bundle: the parsed manifest and a loader.
I18nKeylessClient: The translation engine: a pure-Dart port of i18n-keyless-core plus the store of i18n-keyless-react, with no Flutter import.
I18nKeylessConfig: Everything I18nKeylessClient.init needs.
I18nKeylessStorage: The storage i18n-keyless persists its cache in: translations per namespace, delta cursors, the current language, usage analytics and the device id.
LanguagesConfig: The languages of the project.
MemoryStorage: An in-memory I18nKeylessStorage backed by a map. The default storage.
PQueue: A small priority queue with a concurrency limit, a port of the JavaScript my-pqueue.ts.
StorageKeys: The storage keys, identical to i18n-keyless-react.
StoredSeed: What storage holds for one namespace: its slice, its cursor, and the language it is in.
TranslationOptions: The options of one translation call. Every field is also a named parameter of getTranslation, T(...) and context.t(...).
TranslationsResponse: The answer of GET /translate/:lang: { ok, data: { translations, uniqueId, lastRefresh }, error, message }, plus the ETag header when the API sent one.
UsageResponse: The answer of POST /translate/last-used-translations.

Enums

Lang: Every language i18n-keyless can translate into: the 50 App Store localizations collapsed onto bare language codes, plus the handful of variants that are a different translation (zh-Hans / zh-Hant, pt-BR, es-MX, fr-CA, en-GB).

Constants

availableLangs → const List<Lang>: The 48 supported languages, in the order of the JavaScript AVAILABLE_LANGS array.
defaultApiUrl → const String: The official API.
defaultNamespace → const String: The namespace used when none is provided. It reuses the legacy storage keys so the key names are identical to the JavaScript SDKs.
i18nKeylessSdkRuntime → const String: The sdk header: what kind of client this is at runtime. A Flutter app is a device, counted by its persisted unique_id. The protocol (docs/PROTOCOL.md, section 10.1) gives this port the label flutter: the API treats every label that is not node, laravel or *-server as a device.
i18nKeylessVersion → const String: The package version, sent as the Version header on every request.

Properties

availableLangCodes → List<String>: The 48 supported codes (ar, bn, ..., vi), same order as availableLangs.
final

Functions

applyReplace(String text, Map<String, String>? replace) → String: Replaces every placeholder of replace in text in one pass. Regex-special characters in the placeholders are escaped, so {name}, $price or (x) all work. An empty replacement keeps the placeholder, like the JavaScript SDKs.
buildDictionaryUrl({required String apiUrl, required String lang, String? lastRefresh, String? namespace, String? etag}) → String: The URL of GET /translate/:lang (protocol section 4.2). Without an ETag the delta cursor travels as last_refresh= (a null cursor is written literally as null, an empty one as empty); with an ETag the cursor leaves the URL. The default namespace never appears; another namespace is URL-encoded.
bundleCovers(BundleManifest? manifest, String namespace, String lang) → bool: True when the manifest lists lang under namespace.
bundleNamespaces(BundleManifest? manifest) → List<String>: The namespaces the manifest lists, in manifest order.
etagCacheKey(String apiKey, String lang, [String? namespace]) → String: The in-memory ETag map key of one dictionary: apiKey|lang|namespace.
generateUniqueId() → String: Generates a device id with the same shape as one the API would have minted.
isUniqueId(Object? value) → bool: True for a value usable as the header: non-empty, at most 64 printable ASCII characters (a newline in a header value makes the HTTP client throw).
loadBundleSeed(I18nKeylessBundle? bundle, String namespace, Lang lang, {void log(String message)?}) → Future<BundleSeed?>: Loads one covered dictionary from the bundle. null when the manifest does not cover the pair, when the loader yields nothing, or when it throws (a missing file at runtime is a miss like any other: the caller falls back to the fetch).
mergeBundleWithStorage(BundleSeed bundle, StoredSeed? stored, String lang) → BundleSeed: The precedence between the bundle and what storage holds for the same namespace.
queueIdFor(String namespace, String key) → String: The id of a translate task in the queue: namespace:key. The context and the origin language are not part of it (protocol section 15, item 1).
resolveLang(String? tag, {Iterable<Lang>? supported, Lang? fallback}) → Lang?: Resolves any BCP-47 locale tag (Platform.localeName, Localizations.localeOf, an Accept-Language entry) onto a supported Lang, most specific match first:
resolveNamespace(TranslationOptions? options, String? configDefault) → String: The effective namespace of a call: the per-call TranslationOptions.namespace, else the config defaultNamespace, else the literal default. Empty strings fall through.
resolveOriginLanguage(TranslationOptions? options, Lang primary) → Lang?: The origin language of a UGC key: the per-call TranslationOptions.originLanguage when it exists and differs from primary, null otherwise (regular flow).
storageKeyFor(String key, String? context) → String: The storage key of a translation: "key__context" when a context is given, the key itself otherwise (an empty context counts as none, like the JavaScript SDKs).
toAppStoreLocale(Lang lang) → String: The App Store Connect locale shortcode for a Lang: toAppStoreLocale(Lang.fr) is fr-FR, toAppStoreLocale(Lang.pt) is pt-PT.

Typedefs

BundleLoader = FutureOr<Translations?> Function(String namespace, Lang lang): Reads one file of the bundle: the dictionary of <namespace>/<lang>.json, or null when the app has no such file. Called only for a pair the manifest covers.
GetAllTranslations = Future<TranslationsResponse> Function(): A custom GET /translate/:lang replacement: returns the whole dictionary of the current language.
HandleTranslate = Future<HandleTranslateResult> Function(String key): A custom POST /translate replacement: called with the source text on a miss.
I18nKeylessLogger = void Function(String message): A log sink. Defaults to print.
QueueTask<T> = Future<T> Function(): A task the queue runs.
SendTranslationsUsage = Future<UsageResponse> Function(TranslationsUsage usage): A custom POST /translate/last-used-translations replacement. It receives the default-namespace usage bucket, like the JavaScript SDKs hand their custom handler.
Sleep = Future<void> Function(Duration duration): Waits duration. Injectable so tests replay the backoff schedule without waiting.
Translations = Map<String, String>: The translations for a language: { "un texte": "a text" }. A key with a context is stored as "key__context".
TranslationsUsage = Map<String, String>: Usage per key: { "un texte": "2025-06-23" } (date of last use, YYYY-MM-DD).

i18n_keyless_core library

Classes

Enums

Constants

Properties

Functions

Typedefs

i18n_keyless package

i18n_keyless_core library