sheety_localization 0.7.0-dev
sheety_localization: ^0.7.0-dev copied to clipboard
Generate Flutter (Dart), TypeScript and Python localization code from Google Sheets, with ICU plural/select support, validation, and AI-assisted translation of missing cells.
0.7.0-dev #
- BREAKING:
generateno longer writes ARB files and no longer runsflutter gen-l10n— it parses the sheet itself and emits the code directly. Generation needs only the Dart SDK; CI no longer has to download Flutter. - BREAKING: Removed
--arb,--prefix,--author,--comment,--context,--modifiedand--[no-]last-modified(they only shaped ARB files); using one fails with a migration hint.--lib/--genkeep working as a shortcut for the Dart target. - BREAKING: A real parent locale column now wins over its regional variant:
arkeeps its own texts instead of being overwritten byar_EGwhen the regional column comes later in the header, and an empty cell of a real parent column falls back to the base language instead of borrowing the regional text (e.g.pano longer takespa_PKtexts). A synthetic parent (ptfrompt_BR) is still created when the parent column is missing.--legacy-regional-overriderestores the 0.6.0 behaviour. - BREAKING: Duplicate labels in a sheet (after sanitizing) are now an error instead of the later row silently overwriting the earlier one.
- BREAKING: A row whose trailing cells are empty is no longer dropped from every locale — the missing translations fall back to the parent locale, then to the base language. A row with an empty base text is left out with an
empty-basewarning. - BREAKING:
generateneeds a target: 0.6.x defaulted--libtolib, so a baregenerate --sheet=…now exits with code 64. Pass--lib=libor--dart=lib. - BREAKING:
--include-emptyis now on by default (rows with empty trailing cells are kept and fall back).--no-include-emptyrestores the 0.6.x behaviour. - BREAKING: For a sheet whose base language is not
enbut which has anencolumn, missing cells fall back to the base language, and the "In xx, this message translates to" doc comments show the base text. 0.6.x used English (the gen-l10n template) for both. - BREAKING: The library (
package:sheety_localization/sheety_localization.dart) exports thelocalizeAPI as before plusrunGenerateand the exit codes; the internals ofgenerateare not public API. - FIX:
localizereads the header exactly asgeneratedoes: header cells (column D too) are sanitized (pt BR→pt_BR) and must be locale codes, and a second column of the same locale is skipped, so aNotescolumn or a secondpt_brcolumn is no longer filled with translations. - FIX:
localizewrites only translations thatgenerateaccepts: an ICU source must give a translation its ICU parser accepts (no{name, number},=5,selectordinal), placeholders keep their kind, and a{{name}}source keeps its{{name}}placeholders. One-word plural or select branches (one{item}) are no longer mistaken for placeholders. - FIX:
localizeskips a row whose source text is empty instead of translating its label, and both executables treat a cell holding only whitespace as empty. - FIX:
localizequotes the sheet title when reading a sheet, so a sheet named like a cell (v2,web1,ios16) is read instead of a cell of the first sheet. - FIX: An invalid credentials file no longer prints part of the private key in the error message (
localizeandgenerate). - ADDED: Flutter Dart target (
--dart), a drop-in replacement for the gen-l10n output: same files, classes,of(context), delegates,supportedLocales, lookup andintlplural/select behaviour (verified byte for byte against gen-l10n output of a real 59-locale sheet). - ADDED: Metadata API in the Dart output for tests:
localizationScopes,XLocalization.messages(key, description, placeholders with type and example), per-localetemplatesandfallbackKeys, and a dynamicformat(key, args). Turn it off with themetadata: falsetarget option for a gen-l10n-identical output. - ADDED: TypeScript target (
--ts) for Astro / SolidJS: zero-dependency ESM, strict types, one module per locale with lazyloaders,resolveLocale, an eager bundle for SSR and a separatemetamodule. - ADDED: Python target (
--python) for backends: zero-dependency package (Python ≥ 3.9,mypy --strictclean), snake_case typed accessors, lazy per-locale modules,get(locale)withAccept-Languagenegotiation, a dynamicformat(key, **args)and metadata. - ADDED: Plurals behave identically in all three targets: TypeScript and Python embed CLDR 48 plural rules and reproduce
intl's selection (exact=0/=1/=2matches first,two → few → otherfallback). - ADDED:
{{name}}(mustache) placeholders for chosen sheets (syntax: { mustache: [...] }/--mustache), emitted as typed parameters like ICU{name}. - ADDED: Validation with sheet/cell locations (
plural-exact-as-categorywarns when=1stands in for a category that covers more numbers, like Russianone;{{{name}}}gets a clear error): ICU syntax, placeholder mismatches against the base text, missingotheror CLDR plural categories, markup tag mismatches, duplicate labels, reserved words and identifier collisions per target, unsupported meta, invalid locale columns. Errors stop generation before anything is written;--strictalso fails on warnings;--diagnostics-format=json|githubfor CI, also for command-line, configuration, credentials and unexpected errors (usage-error,config-error,internal-error), with annotation paths relative to the workspace. - ADDED:
sheety.yamlconfiguration with per-targetoutput,include/ignoresheet filters and emitter options; command-line flags override it. - ADDED: Generated output is tracked by a deterministic
sheety_manifest.json: only changed files are rewritten, stale generated files are removed (a stale file edited by hand is kept and released instead, with amodified-generated-filewarning), files the generator does not own are never touched. Without a manifest entry a file is taken over only when it is identical or carries the whole generated header (took-over-filewarning). Paths Windows cannot create (con,nul, …) are rejected (reserved-file-name).--checkreports outdated output without writing (exit code 1). - ADDED:
--dump-snapshot/--snapshotto save the sheet to a JSON file and generate from it offline. - ADDED:
invalid-unicodewarning for cells with lone UTF-16 surrogates (values keep them, comments and docstrings show U+FFFD in every target) andplural-rules-mismatchwarning when the Dart target (intl has no rules for e.g.gd,gv,kw) and the TypeScript/Python targets (CLDR) would render a plural differently. - ADDED: The TypeScript and Python runtimes negotiate locales with one documented algorithm (Accept-Language q-values, POSIX forms, script/region candidates, deprecated codes such as
iw→he, then any locale of the language), checked by a shared test table. - CHANGED: Dart output is formatted at the page width of the nearest
analysis_options.yaml(or thepage_widthtarget option) and in the style of the language version of the nearestpubspec.yaml(short style below Dart 3.7), asdart formatwould in place. - CHANGED: Writing is staged: every target's new files are written to a staging directory of its own (
.sheety-staging-<target>) first and moved into place only when all of them could be written; a failure reports exactly which targets were written and which one was left partly written. Renaming a sheet by case only works on case-insensitive file systems. - CHANGED: Stricter configuration: the output directories of two targets must not be the same or nested, compared through symlinks and case on case-insensitive file systems;
--sheetreplaces asnapshot:ofsheety.yaml(and--snapshotasheet:), both in one place is an error; target options are type-checked and the TypeScript and Python targets reject unknown options; command-line RegExp lists split only at commas outside{},[]and();--checkdoes not write the--dump-snapshotfile. - CHANGED: A manifest of another target in an output directory is an error (
foreign-manifest) instead of being trusted; scope names that give the same class or directory in a target (rate-us-2/rate_us2) are reported; names that would break the generated code are reserved (Dart keysintl,override,int,num,double,dynamic, placeholdersintl,localeName; TypeScript keythen) while Dart keyskey/args, Python keys named like builtins (property,str, …) and Dart locales that are reserved words (Locales.is$) now work. - CHANGED: The generator moved to
lib/src/generate/behind interfaces (sheet source, emitters, writer) and is covered by unit, golden and integration tests (flutter analyze,tsc --strict,mypy --strict, cross-target rendering parity).
0.6.0 #
- FIX:
localizeskipped any sheet whose base language was not English — alabel | description | meta | ru | ...header was rejected as "not a localization sheet". The fourth column is now accepted as the source language whenever it is a recognized language code (ru,de,pt_BR, …); non-language data columns (e.g. aFamilyreference table) are still skipped. The source language is carried through into the model prompt and JSON schema, so rows are translated from the actual base language instead of always "from English". - FIX:
generatehard-coded theflutter gen-l10ntemplate to<prefix>_en.arb, so a bucket without an English column failed to generate. The template is now chosen per bucket — English when present (unchanged behaviour), otherwise the first available ARB — so a non-English base language generates too.
0.5.0 #
- BREAKING:
localizenow only writes to a sheet whose header matcheslabel | description | meta | en | <locale> .... A sheet whose fourth column is not the English source is skipped with a warning — reference tables kept in the same spreadsheet were previously "translated", overwriting their data. - FIX:
localizewrote nothing back to Google Sheets — the row stream introduced in 0.4.3 never emitted the localized rows. - FIX:
localizefailed every request with400 Unsupported parameter: 'temperature'on the defaultgpt-5-minimodel. Reasoning models (gpt-5*,o*) now getreasoning: {effort: low}instead of the sampling parameters, and a token budget with headroom for their reasoning tokens. - FIX: Placeholder validation rejected every correctly translated ICU plural, and accepted translations that had flattened the directive away. Placeholders are now parsed by brace depth.
- FIX: A reasoning item carrying the model's thinking is no longer mistaken for the answer payload.
- FIX: A sheet title containing a space or an apostrophe produced an invalid A1 range, so the row could not be written.
- FIX: Two columns whose headers sanitize to the same locale (
pt-BRandpt_BR) left the second one empty forever; the duplicate column is now skipped. - CHANGED: Failed writes to Google Sheets are retried only when retrying can help (429, 5xx, network) — a malformed range or a missing scope no longer costs 60s of sleeping per row.
- CHANGED: A single OpenAI request now has a hard timeout (
--timeout, default 120s), and retries are limited to transient failures; an unusable payload is answered by splitting the batch instead of re-sending the same prompt. - CHANGED: An invalid numeric option (
--workers=abc,--batch=99) is reported instead of being silently replaced by the default. - CHANGED: The pipeline moved to
lib/, behind interfaces for both the model (LocalizationClient) and the spreadsheet (SheetsGateway), and is covered by unit tests — including the sheet-write path that used to be reachable only through a live Google account. - ADDED: Per-language fallback: a failed batch of languages is split and each language is retried on its own instead of being re-sent as a whole, so one rare language the model chokes on no longer breaks its neighbours.
- ADDED: Translation validation before writing: ICU placeholders and markup tags must survive, no empty values, no leaked markdown fences, no runaway output. A rejected translation is retried alone.
- ADDED: Language hints in the prompt and in the JSON schema — English name, native endonym and an explicit disambiguation note for codes models misread (
ukis Ukrainian, not "United Kingdom"). - ADDED:
--timeoutoption (default120s) — a request the model never finishes is aborted instead of stalling a worker. - CHANGED: Retries are limited to transient failures (network, timeout, 429, 5xx). Unusable payloads are never re-sent with the same prompt.
- CHANGED:
max_output_tokensscales with the number of requested languages, so a large batch is no longer truncated into invalid JSON. - CHANGED: A row that cannot be written to the sheet is skipped instead of aborting the whole run.
- CHANGED: The localization pipeline moved to
lib/and is covered by unit tests.
0.4.3 #
- CHANGED:
localizenow writes translated cells to Google Sheets via batch updates per row instead of one request per cell. - CHANGED:
--workersnow controls real concurrent OpenAI requests during localization.
0.4.2 #
- ADDED: Configurable language batch size via
--batch(-b) CLI parameter to control how many languages are translated per single API call (default: 3). - CHANGED: Default OpenAI model updated from
gpt-4o-minitogpt-5-mini.
0.4.1 #
- ADDED: Language name hints in localization prompts to prevent AI misinterpretation of ambiguous ISO codes (e.g.
ukas Ukrainian, not United Kingdom).
0.4.0 #
- FIX: Fix aggressive caching of translations that caused outdated translations to be used.
0.3.0 #
- FIX: Resolved issue with
--no-last-modifiedflag not functioning as intended. - ADDED: Introduced localization with ChatGPT for improved translation quality.
0.2.3 #
- ADDED: Optional handling of rows with missing locale columns via
--include-empty. - CHANGED: Default behavior now skips rows with incomplete localization data.
- ADDED: Ability to disable generation of
@@last_modifiedmetadata using--no-last-modified.
0.2.2 #
- ADDED: Optional support for ignoring specific sheets by title with RegExp patterns.
0.2.1 #
- FIX: Fix locales import to
dart:ui
0.2.0 #
- ADDED: Support for generating Flutter locales file.
- ADDED: Gen missing base locales.
0.1.3 #
- ADDED:
ignore_for_file: directives_orderingfor generated files to prevent linting issues.
0.1.2 #
- Add usage examples to the documentation.
0.1.1 #
- Updated documentation to clarify usage.
- Convert README.md to UTF-8 encoding.
0.1.0 #
- Initial release with basic functionality.