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.
Sheety Localization #
Sheety Localization turns a Google Sheet into localization code. Translators and product people edit one spreadsheet, and a single command generates:
- Flutter (Dart): a drop-in replacement for the
flutter gen-l10noutput. It has the same classes,of(context), delegates and lookup, plus a metadata API for tests. - TypeScript: zero-dependency ES modules for Astro, SolidJS or any bundler, with one lazily loaded module per locale.
- Python: a zero-dependency typed package for a backend (FastAPI, Django,
workers), with
Accept-Languagenegotiation.
Warning
The generation process changed in 0.7.0. generate no longer writes ARB
files and no longer runs flutter gen-l10n: it reads the sheet and writes the
Dart, TypeScript and Python code itself. The ARB-only options (--arb,
--prefix, --author, …) are removed, a target (--dart, --ts,
--python or sheety.yaml) is required, and the sheet is validated more
strictly: duplicate labels and empty base texts are now errors. Read
Migrating from 0.6.x before upgrading.
The package ships two executables:
| Executable | What it does |
|---|---|
generate |
Reads the sheet, validates every cell and writes the code for the configured targets |
localize |
Fills in missing translations in the sheet with the OpenAI API and writes them back |
Both read the same sheet layout.
Contents #
- Features
- Sheet layout
- Installation
- Google credentials
- Quick start
- Configuration:
sheety.yaml - Command line
- Flutter (Dart) target
- TypeScript target (Astro, SolidJS)
- Python target (FastAPI)
- Locale negotiation (TypeScript and Python)
- Packaging the output for a registry
- CI
- Diagnostics
- Migrating from 0.6.x
- AI-powered localization (
localize) - Docker
- Tips
A complete, runnable example (sheet snapshot, configuration and the generated
output of all three targets) is in example/.
Features #
- One sheet, three languages. Each sheet (tab) becomes a scope: a class in Dart, a module directory in TypeScript and a sub-package in Python.
- Per-target sheet selection. For example, the Flutter app gets
app/chat/settingsand the backend gets thebackend-*sheets. - ICU messages: placeholders,
pluralandselect(nested too), with the semantics ofpackage:intlin every target. A plural picks the same branch in Dart, TypeScript and Python. (JavaScript has one number type, so anumplaceholder holding1.0prints1in TypeScript and1.0in Dart and Python; declare itdoubleto get1.0everywhere, or pass integers.) {{name}}(mustache) placeholders for sheets that use them, typically backend or e-mail texts.- Validation before anything is written. Each error and warning names the
sheet, the cell (
app!E12), the locale and the key, so an editor can fix the sheet.--strictalso fails on warnings, and--diagnostics-format=githubannotates the CI run. - Fallbacks: an empty cell uses the parent locale (
pt_BR→pt), then the base language. The generated metadata records every fallback. - Safe, deterministic output: no timestamps, and only changed files are
rewritten. A
sheety_manifest.jsonrecords which files the generator owns: it deletes its own stale files and never touches anything else, so apubspec.yaml,package.jsonorpyproject.tomlcan live next to the generated code. --checkreports outdated output without writing anything (exit code 1).- Offline runs:
--dump-snapshotsaves the sheet to JSON, and--snapshotgenerates from it with no Google access. - No Flutter needed to generate: only the Dart SDK. The generated Dart
code still uses
flutter_localizationsandintlin your app.
Sheet layout #
Every localization sheet has the same layout. Row 1 is the header:
A: label |
B: description |
C: meta |
D: base locale | E… : locales |
|---|---|---|---|---|
title |
Application title | Sheety Notes | Sheety Notizen | |
greeting |
Greets the user | {"placeholders": {"name": {"type": "String", "example": "Alice"}}} |
Hello, {name}! | Hallo, {name}! |
notes |
Number of notes | {"placeholders": {"count": {"type": "int", "example": "3"}}} |
{count, plural, =0{No notes} one{One note} other{{count} notes}} |
{count, plural, =0{Keine Notizen} one{Eine Notiz} other{{count} Notizen}} |
-
labelis the message key. It is sanitized: every character outside[a-zA-Z0-9_]becomes_, repeated_are merged and leading and trailing_are trimmed, sochat.welcome.1becomeschat_welcome_1. Dart and TypeScript use the key as is (chatWelcome). Python uses the snake_case form (chat_welcome) as the attribute name and keeps the key forformat(). -
descriptionbecomes the doc comment of the generated getter or method. Adescriptioninmetaoverrides it. -
metais empty or a JSON object in the ARB@keyformat:{ "description": "Number of notes in the list", "placeholders": { "count": { "type": "int", "example": "3", "description": "How many" } } }The placeholder
typeis one ofString,int,num,doubleorObject.exampleis used by the generated metadata (see the test examples below). A placeholder that is used in a text but not declared is inferred, as gen-l10n does: a plural count isnum, a select choice isString, anything else isObject. Placeholders are ordered as declared, then the undeclared ones alphabetically. The generated parameters follow this order.Not supported (error
unsupported-meta): the typeDateTime, an unknown type,format,optionalParameters,isCustomDateFormat. Pass a preformattedStringinstead. -
Column D is the base language, the source every other column is translated from and the final fallback. It does not have to be
en; each sheet can have its own base. -
Columns E onwards are locales:
de,pt_BR,pt-BR,zh_Hant,zh_Hant_TW,es_419… They are normalized toll,ll_CC,ll_Ssssorll_Ssss_CC. A header cell is sanitized first (pt BR→pt_BR), exactly as for column D. A header that is not a locale code is skipped with a warning. A duplicate locale (pt-BRnext topt_BR) keeps the first column.localizereads the header the same way, so it never fills a column thatgenerateskips (aNotescolumn, a secondpt_br). -
A cell that holds only whitespace counts as empty in both executables.
-
A sheet whose fourth header cell is not a language code (a
helptab, a reference table) is not a localization sheet. It is skipped (not-localization-sheet, info). Useignoreto skip a sheet that matches the layout but should not be generated. -
The sheet title becomes the scope name, sanitized by the same rule (case is kept):
sign-upbecomessign_up(SignUpLocalizationin Dart and Python,sign_upin TypeScript),Sign-UpbecomesSign_Up. A title that is a Dart keyword (default,new) is fine for Dart, whose class is always<Name>Localization; TypeScript and Python reject their own keywords as scope names.
Messages (ICU subset) #
Texts are ICU MessageFormat with the exact semantics of Flutter's gen-l10n and
package:intl:
| Supported | Example |
|---|---|
Literal text; apostrophes and # are literal (no escaping, gen-l10n's default) |
It's #1 |
| Argument | Hello, {name}! |
Plural with =0, =1, =2 and zero one two few many other |
{count, plural, =0{No notes} one{One note} other{{count} notes}} |
| Select | {gender, select, male{he} female{she} other{they}} |
| Nesting (a placeholder or a select inside a plural branch, and so on) | {n, plural, one{{name} has one} other{{name} has {n}}} |
| Markup tags, kept as text but checked across locales | I accept the <b>terms</b> |
How a plural branch is chosen, identically in all three targets: an exact
=0 / =1 / =2 (or zero / one / two) match first, then the CLDR
category of the locale (Unicode CLDR 48). A missing two falls back to few,
then to other, and any other missing category falls back to other.
Fractional counts are handled as package:intl does.
One exception: package:intl, which the Dart target uses at runtime, has no
plural rules for some languages CLDR covers (Scottish Gaelic gd, Manx gv,
Cornish kw, Norwegian Nynorsk nn, Yiddish yi and about a hundred more).
For them intl renders every count without an exact =0/=1/=2 match as
other, while the TypeScript and Python targets use the CLDR rules (gd: 3 is
few). When the Dart target and another target generate a scope with such a
locale and a plural, a plural-rules-mismatch warning names the locale and
the messages that can differ.
A cell that is not valid Unicode text (a lone UTF-16 surrogate, e.g. from a
broken copy-paste) gets an invalid-unicode warning. String values keep it,
escaped, identically in every target; comments and docstrings show U+FFFD
instead, so the files are valid UTF-8.
Rejected with an error (icu-syntax, plural-missing-other):
selectordinal, offset:, {x, number} / date / time, exact cases
other than =0/=1/=2, plural or select without other, unbalanced
braces. gen-l10n silently accepts some of these (a stray } truncates the
message there), but this generator does not.
Mustache sheets ({{name}}) #
Some sheets, typically backend and e-mail texts, use {{name}} placeholders.
List them under syntax.mustache (or pass --mustache). In those sheets:
{{name}}and{{ name }}are placeholders, typed and validated exactly like ICU{name}(declare their type inmetaas usual).- Everything else is literal text: single braces (
{see plans}),#and'. - There is no plural or select.
{{a.b}}, empty{{}}and an unterminated{{are errors.
If an ICU sheet contains {{name}}, the icu-syntax error says that the
sheet looks like a mustache sheet.
Regional columns and fallbacks #
- A real parent column wins. If a sheet has both
arandar_EG,arkeeps its own texts, andar_EGoverrides only the cells it fills. An emptyarcell falls back to the base language, never toar_EG. - A synthetic parent is created only when the parent column is missing.
With
pt_BRbut nopt, aptlocale is generated from thept_BRtexts (synthetic-locale, info), as the previous generator and gen-l10n's class hierarchy (AppLocalizationPtBr extends AppLocalizationPt) require. - Empty cells fall back to the parent locale, then to the base language:
pt_BR→pt→ base. This includes the trailing cells that the Sheets API omits from short rows. Each fallback is recorded in the metadata (fallbackKeys,isFallback) and reported as afallbackinfo with counts. - An empty base cell leaves the message out (
empty-base, warning). The message cannot exist without its source text; the rest is generated, andlocalizeskips such a row instead of translating its label. - Duplicate labels are an error (
duplicate-label). Two rows of a sheet whose labels sanitize to the same key (chat.titleandchat_title) must be merged in the sheet.
Installation #
As a global tool:
dart pub global activate sheety_localization
dart pub global run sheety_localization:generate --help
Or as a dev dependency of the project that holds the generated code (pins the version, so every machine and CI generates the same output):
dart pub add --dev sheety_localization
dart run sheety_localization:generate --help
Requires the Dart SDK ≥ 3.6. Flutter is not required to generate.
dart format (part of the Dart SDK) formats the Dart output; turn it off with
--no-format.
A Docker image with AOT-compiled binaries is also available.
Google credentials #
- Create a project in the Google Cloud Console and enable the Google Sheets API.
- Create a Service Account and download its JSON key, for example as
credentials.json. Never commit it. In CI, write it from a secret. - Share the spreadsheet with the service account's e-mail (the
client_emailin the key). Viewer is enough forgenerate;localizewrites, so it needs Editor. - The spreadsheet ID is the part of the URL between
/d/and/edit.
Quick start #
Generate all three targets from the command line:
dart run sheety_localization:generate \
--sheet=<SPREADSHEET_ID> --credentials=credentials.json \
--ignore='^help$' \
--dart=lib \
--ts=web/src/i18n \
--python=backend/src/myapp/l10n
Or describe the setup once in a sheety.yaml next to it:
sheet: <SPREADSHEET_ID>
credentials: credentials.json
ignore: ['^help$']
syntax:
mustache: ['^backend-']
targets:
dart:
output: app/lib
ignore: ['^backend-']
ts:
output: web/src/i18n
ignore: ['^backend-']
python:
output: backend/src/myapp/l10n
include: ['^backend-']
dart run sheety_localization:generate # reads ./sheety.yaml
dart run sheety_localization:generate --check # CI: is the committed output up to date?
With the example configuration and snapshot, the output is:
Using example/sheety.yaml
Reading snapshot example/snapshot.json...
Read 3 sheets, 3 used by dart, ts, python
dart: 2 scope(s) -> example/dart/lib (13 added, 0 changed, 0 removed, 0 unchanged)
ts: 2 scope(s) -> example/ts/src/i18n (21 added, 0 changed, 0 removed, 0 unchanged)
python: 2 scope(s) -> example/python/src/sheety_notes_l10n (16 added, 0 changed, 0 removed, 0 unchanged)
Done.
Errors and warnings in the sheet are printed above that summary, grouped by scope. If there is any error, nothing is written.
Configuration: sheety.yaml #
generate reads sheety.yaml from the current directory when it exists, or
the file given with --config. Every key is optional except
targets.<target>.output. Paths are relative to the YAML file. Unknown keys
are errors, with a "did you mean" hint. Command-line options override the
file.
The input is either the spreadsheet (sheet) or a snapshot (snapshot),
never both in the same place: setting both in the file is an error, and on the
command line --sheet replaces a snapshot: of the file (and --snapshot a
sheet:), while giving both flags is an error.
# Input ------------------------------------------------------------------------
# Google spreadsheet ID (the part of the URL between /d/ and /edit).
sheet: 1AbC...
# Service account key. Default: credentials.json in the CURRENT directory.
credentials: credentials.json
# Read the sheets from this snapshot instead of Google (offline / CI).
# Format: {"sheets": [{"title": "app", "values": [["label", ...], ...]}]}
snapshot: sheets.json
# Also save every sheet that was read to this file (not with --check, which
# writes nothing).
dump_snapshot: sheets.json
# Sheets skipped by every target: RegExps over sheet titles, unanchored
# ("backend" also matches "backend-mail"; use ^ and $ for exact titles).
# A single string is accepted too.
ignore: ['^help$', '^locales$']
# Message syntax per sheet: these sheets use {{name}} instead of ICU.
syntax:
mustache: ['^backend-']
# Output -----------------------------------------------------------------------
# Header comment of every generated file, without comment markers ("// " or
# "# " is added per language; a leading "//" is stripped). "" for none.
header: This file is generated, do not edit it manually!
# Treat warnings as errors.
strict: false
# Format the Dart output with `dart format`, at the page width of the nearest
# analysis_options.yaml (formatter: page_width), else 80, and in the style of
# the language version of the nearest pubspec.yaml (the lower bound of
# environment: sdk:, e.g. the short pre-3.7 style for sdk: ^3.6.0), else the
# latest. That is what `dart format` itself does in the package.
format: true
# Reader ------------------------------------------------------------------------
# Missing trailing cells of a short row are empty translations, so they fall
# back. false: skip such rows entirely, like 0.6.x did (warning short-row).
include_empty: true
# 0.6.x behaviour: the first regional column of a language (ar_EG) overwrites
# the language's own column (ar). Only for bit-identical migrations.
legacy_regional_override: false
# Targets ----------------------------------------------------------------------
# At least one. Each target needs its own output directory, and the
# directories must not be nested in each other (each target keeps a manifest
# of the files it owns there). Directories are compared through symlinks and,
# on a case-insensitive file system, ignoring case. Per target:
# output (required) directory to generate into
# include only sheets matching one of these RegExps (applied first)
# ignore then skip sheets matching one of these (after the global ignore)
# header overrides the global header for this target
# options emitter options (below)
targets:
dart:
output: app/lib
ignore: ['^backend', '^bot']
options:
directory: src/generated # per-scope files, locales.dart, localization_meta.dart
barrel: localization.dart # library exporting everything; "" for none
metadata: true # false: no metadata API (gen-l10n-identical output)
page_width: 80 # positive integer; overrides analysis_options.yaml
ts:
output: web/src/i18n
ignore: ['^backend']
python:
output: backend/src/myapp/l10n
include: ['^backend']
header: Generated from the localization sheet.
The TypeScript and Python targets have no options yet. An unknown option
(unknown-option) and a value of the wrong type (invalid-option, e.g.
metadata: "false" or page_width: "100") are errors.
Command line #
dart run sheety_localization:generate [options]
| Option | Meaning |
|---|---|
--config=<file> |
Configuration file (default: ./sheety.yaml when it exists) |
-s, --sheet=<id> |
Google spreadsheet ID |
-c, --credentials=<file> |
Service account key (default credentials.json) |
--snapshot=<file> |
Read the sheets from a snapshot instead of Google |
--dump-snapshot=<file> |
Save the sheets that were read. Works without any target; not with --check |
-i, --ignore=<re> |
Sheets skipped by every target (repeat, or separate with commas) |
--mustache=<re> |
Sheets using {{name}} placeholders |
--[no-]include-empty |
See include_empty (default on) |
--[no-]legacy-regional-override |
See legacy_regional_override (default off) |
--dart=<dir>, --ts=<dir>, --python=<dir> |
Enable a target, or override its output |
--<target>-include=<re>, --<target>-ignore=<re> |
Per-target sheet filters (replace the YAML lists) |
--only=dart,ts,python |
Generate only these of the configured targets |
--header=<text> |
Header comment of every generated file |
-f, --[no-]format |
dart format the Dart output (default on) |
--check |
Write nothing (not even --dump-snapshot); list what would change, exit 1 if anything would |
--[no-]strict |
Warnings are errors |
-v, --verbose |
List every written file and print info diagnostics |
--diagnostics-format=text|json|github |
How diagnostics are printed (see CI) |
RegExps passed on the command line (--ignore, --mustache,
--<target>-include, --<target>-ignore) may be repeated or separated with
commas. A comma inside {}, [] or () does not split (--ignore=^a{1,2}$
is one pattern), and \, is a literal comma. In sheety.yaml, use a list.
Exit codes: 0 success, or up to date with --check; 1 --check found
differences; 2 errors (sheet diagnostics, unreadable source, output
conflicts); 64 invalid usage (unknown or removed option, bad config).
Flutter (Dart) target #
Output #
With the default options and output: lib:
lib/
├── localization.dart barrel: exports flutter_localizations and everything below
├── sheety_manifest.json files owned by the generator (see Packaging)
└── src/generated/
├── locales.dart class Locales { static const Locale en, pt$BR, ...; values }
├── localization_meta.dart metadata API (LocalizationScope, localizationScopes, ...)
├── app/
│ ├── app_localization.dart abstract class AppLocalization, delegate, lookupAppLocalization
│ ├── app_localization_en.dart one file per language...
│ └── app_localization_pt.dart ...with its regional subclasses (AppLocalizationPtBr)
└── sign_up/
└── ...
These are the same files, classes and signatures that flutter gen-l10n
produced with 0.6.x (--no-nullable-getter, output class
<Scope>Localization). Existing call sites keep compiling. The generated code
imports package:flutter, package:flutter_localizations and
package:intl, so the package that contains it needs:
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any # the version pinned by flutter_localizations
flutter: generate: true and l10n.yaml are not needed.
Usage #
import 'package:my_localization/localization.dart';
MaterialApp(
localizationsDelegates: const [
...AppLocalization.localizationsDelegates, // includes the Global* delegates
SignUpLocalization.delegate,
],
supportedLocales: AppLocalization.supportedLocales,
home: Builder(
builder: (context) {
final l10n = AppLocalization.of(context);
return Text('${l10n.title}: ${l10n.notes(3)}');
},
),
);
// Outside the widget tree:
final de = lookupAppLocalization(Locales.de);
de.greeting('Alice'); // Hallo, Alice!
Locales names a field after the locale (en, pt$BR, zh$Hant$TW); a
locale code that is a Dart reserved word gets a trailing $ (Locales.is$
for Icelandic). Which class a Locale gets is decided by
lookup<Scope>Localization exactly like gen-l10n: language + script +
country, then language + script, then language + country, then the
language; which Locale the app runs in is Flutter's locale resolution over
supportedLocales.
Some names cannot be keys or placeholders because the generated code needs
them (reserved-word): the keys intl, override, int, num, double
and dynamic (they would hide the intl import prefix, @override and
types the class uses), gen-l10n's own members (localeName, of,
delegate, ...), and the placeholders intl, localeName and _temp0,
_temp1, ... (names the method bodies use).
Metadata API (for tests) #
Unless metadata: false is set, the output also has a small reflection layer,
generated into localization_meta.dart, so no runtime package is needed:
| API | What it gives |
|---|---|
localizationScopes |
Every scope: name, baseLocale, supportedLocales, messages, delegate, lookup(Locale) |
AppLocalization.messages |
Every message in sheet order: key, description, placeholders (name, type, example, description, exampleValue), isGetter, exampleArguments |
l10n.templates |
The source text of every message in this locale as written in the sheet: ICU, or mustache for a mustache sheet (fallbacks resolved) |
l10n.fallbackKeys |
Keys that this locale has no text of its own for |
l10n.format(key, args) |
Renders a message by key with named arguments, like calling the getter or method. Throws ArgumentError for an unknown key or a missing or mistyped argument. Numbers are checked by value, the same on the VM and the web: a double placeholder accepts any number, an int one a whole number (2.0, not 2.5) |
Every generated class implements LocalizationBundle (localeName,
templates, fallbackKeys, format). Because of that, messages,
templates, fallbackKeys, format and localizationArgument (the helper
format calls) cannot be used as keys in the sheet (reserved-word); with
metadata: false they can. The keys key and args are fine: format
calls them as this.key / this.args(...).
This test renders every message of every locale of every scope with the
examples from the meta column. It catches a broken plural, a missing
argument or a text that would throw, for every locale:
import 'package:flutter_test/flutter_test.dart';
import 'package:my_localization/localization.dart';
void main() {
for (final scope in localizationScopes) {
group(scope.name, () {
for (final locale in scope.supportedLocales) {
test('$locale', () {
final l10n = scope.lookup(locale);
for (final message in scope.messages) {
final text = l10n.format(message.key, message.exampleArguments);
expect(text, isNotEmpty, reason: '${scope.name}.${message.key}');
for (final p in message.placeholders) {
expect(text, isNot(contains('{${p.name}}')),
reason: '${scope.name}.${message.key} ($locale)');
}
}
expect(l10n.templates.keys,
containsAll(scope.messages.map((m) => m.key)));
});
}
});
}
}
exampleValue parses example for int/num/double placeholders (1
when it is missing). For the other types it uses example, or the
placeholder name when there is none.
TypeScript target (Astro, SolidJS) #
Output #
web/src/i18n/
├── index.ts export * as app ...; scopes, supportedLocales, baseLocale, resolveLocale()
├── meta.ts metadata of every scope (tests, tooling)
├── runtime.ts plural/select helpers, CLDR rules, negotiateLocale(), formatMessage(), types
├── sheety_manifest.json
└── app/
├── index.ts scope, baseLocale, locales, type Locale, loaders, resolveLocale(), loadMessages()
├── types.ts type AppMessages, type AppKey
├── en.ts export const messages: AppMessages (frozen), one module per locale
├── pt-BR.ts
├── eager.ts every locale statically imported, for SSR and static sites
└── meta.ts entries (raw templates, placeholders, fallbacks), format()
The output is ESM with explicit .js import suffixes. It compiles cleanly
under strict, noUncheckedIndexedAccess and verbatimModuleSyntax, with
both NodeNext and Bundler resolution, and has no dependencies. Locale
modules are named by BCP 47 tag (pt-BR). Keys are the sheet keys. A message
without placeholders is a string. A message with placeholders is a function
of an object with one property per placeholder: String is string,
int/num/double are number, and Object is string | number.
A key cannot be then (a dictionary with a then member is a "thenable",
so the Promise of its lazy loader would never resolve to it) or a member of
Object.prototype (constructor, toString, __proto__, ...).
import { app } from './i18n/index.js';
const locale = app.resolveLocale(navigator.languages); // 'de-AT' -> 'de' -> base
const t = await app.loaders[locale](); // one chunk per locale
t.title; // 'Sheety Notizen'
t.notes({ count: 3 }); // '3 Notizen'
await app.loadMessages('pt-PT'); // resolve + load in one call
resolveLocale accepts a tag or a list of tags. It matches case-insensitively
(_ and - alike), drops subtags from the end (zh-Hant-TW → zh-Hant →
zh) and returns the base locale when nothing matches.
SolidJS (@solid-primitives/i18n) #
The dictionaries are plain objects of strings and functions, which is the
shape @solid-primitives/i18n expects:
import * as i18n from '@solid-primitives/i18n';
import { createResource, createSignal } from 'solid-js';
import { app } from './i18n/index.js';
export function useI18n() {
const [locale, setLocale] = createSignal<app.Locale>(app.resolveLocale(navigator.languages));
const [dict] = createResource(locale, (l) => app.loaders[l]()); // lazy, per locale
const t = i18n.translator(dict);
return { locale, setLocale, t };
}
// t('title'), t('notes', { count: 3 })
When the dictionaries must be there synchronously (SSR, tests), import the eager bundle:
import { messages } from './i18n/app/eager.js';
const t = i18n.translator(() => messages.de);
Astro #
// astro.config.mjs
import { defineConfig } from 'astro/config';
import { app } from '@acme/l10n'; // or a relative import of the generated index
export default defineConfig({
i18n: { locales: [...app.locales], defaultLocale: app.baseLocale },
});
---
// src/pages/[...].astro (or any component)
import { app } from '@acme/l10n';
const locale = app.resolveLocale(Astro.currentLocale ?? Astro.preferredLocaleList ?? []);
const t = await app.loaders[locale]();
---
<h1>{t.title}</h1>
<p>{t.notes({ count: 2 })}</p>
Metadata (tests) #
meta.ts is separate, so production bundles never include it:
import assert from 'node:assert/strict';
import * as meta from './i18n/meta.js';
import type { MessageEntry } from './i18n/index.js';
interface ScopeMeta<L extends string> {
readonly scope: string;
readonly locales: readonly L[];
readonly entries: readonly MessageEntry<L>[];
format(locale: L, key: string, args?: Readonly<Record<string, unknown>>): Promise<string>;
}
async function checkScope<L extends string>(scope: ScopeMeta<L>): Promise<void> {
for (const locale of scope.locales) {
for (const entry of scope.entries) {
const args = Object.fromEntries(
entry.placeholders.map((p) => [
p.name,
p.type === 'String' || p.type === 'Object' ? (p.example ?? p.name) : Number(p.example ?? 1),
]),
);
const text = await scope.format(locale, entry.key, args);
assert.ok(text.length > 0, `${scope.scope}.${entry.key} (${locale})`);
}
}
}
await checkScope(meta.app);
await checkScope(meta.sign_up);
Each entry has key, description, placeholders (name, type,
example, description, declared) and templates[locale] (raw,
isFallback, source).
Python target (FastAPI) #
Output #
The output directory is itself a package. All imports inside it are
relative, so it works as a top-level package (src/myapp_l10n) or as a
sub-package of your application (myapp/l10n).
myapp/l10n/
├── __init__.py SCOPES, SUPPORTED_LOCALES, BASE_LOCALE, get(scope, locale), resolve_locale()
├── _runtime.py Localization base class, Message, Placeholder, CLDR plural rules,
│ negotiate_locale(), parse_accept_language()
├── py.typed
├── sheety_manifest.json
└── backend_mail/
├── __init__.py class BackendMailLocalization (abstract), get(locale), resolve_locale(),
│ LOCALES, BASE_LOCALE, MESSAGES, SCOPE, SHEET_TITLE, SYNTAX
├── _en.py one module per locale, imported on first use
└── _de.py
Python ≥ 3.9, no dependencies, and mypy --strict clean. Messages are
snake_case properties (no placeholders) or keyword-only methods: String is
str, int is int, num/double are float, and Object is object.
from myapp.l10n import backend_mail, get
l10n = backend_mail.get("de-CH, de;q=0.9, en;q=0.5") # a tag, a list or an Accept-Language header
l10n.welcome_subject(name="Alice") # 'Willkommen bei Sheety Notes, Alice!'
l10n.LOCALE # 'de'
# Keys known only at runtime: the sheet key (or the raw label) and the
# placeholder names from the sheet.
get("backend-mail", "ru").format("trial.ends", days=7)
get(locale) negotiates the locale as described in
Locale negotiation. Instances are
cached.
A message may be named like a Python builtin (property, str, int, ...):
such a scope refers to the builtins as _builtins.property, _builtins.str,
so the class still works and type-checks.
FastAPI #
from typing import Annotated, Dict
from fastapi import FastAPI, Header
from myapp.l10n import backend_mail
app = FastAPI()
@app.get("/welcome")
def welcome(name: str, accept_language: Annotated[str, Header()] = "en") -> Dict[str, str]:
l10n = backend_mail.get(accept_language)
return {"subject": l10n.welcome_subject(name=name), "locale": l10n.LOCALE}
Metadata (tests) #
import importlib
import pytest
import myapp.l10n as l10n
def example_value(placeholder):
if placeholder.type == "int":
return int(placeholder.example or 1)
if placeholder.type in ("num", "double"):
return float(placeholder.example or 1)
return placeholder.example or placeholder.name
CASES = [
(scope, locale)
for scope in l10n.SCOPES
for locale in importlib.import_module(f"{l10n.__name__}.{scope}").LOCALES
]
@pytest.mark.parametrize("scope,locale", CASES)
def test_every_message_renders(scope, locale):
localization = l10n.get(scope, locale)
for message in localization.MESSAGES:
args = {p.name: example_value(p) for p in message.placeholders}
assert localization.format(message.key, **args)
assert message.key in localization.TEMPLATES
Each localization also has TEMPLATES (raw texts by key), FALLBACK_KEYS and
LOCALE. MESSAGES entries have key, attribute, description and
placeholders (name, parameter, type, example, description).
Locale negotiation (TypeScript and Python) #
resolveLocale / negotiateLocale (TypeScript) and get /
resolve_locale / negotiate_locale (Python) implement one algorithm; a
shared test table runs against both runtimes:
- The request is one tag (
pt-BR), an HTTPAccept-Languageheader (anything containing,or;), a list of tags in order of preference (navigator.languages), or nothing (then the base locale). - An
Accept-Languageheader is split at,; each item istag;param;.... Aq(orQ) value must be a plain decimal number (0.8,1,.5): above 1 counts as 1, anything else (bad,1e-1) as 0. Items with weight 0 and*are dropped; the rest is sorted by weight, equal weights keep their order. - Each tag is normalized: ASCII whitespace around it is ignored, so is
everything from the first
.or@(en_US.UTF-8,de_AT@euro); the rest is split at-and_. The first subtag must be a 2-3 letter language (C,*and the like are skipped), then an optional 4-letter script and an optional 2-letter or 3-digit region are taken while they come in that order; anything else (extensions-u-...,-x-...) ends the tag. Case is normalized (zh-hant-tw->zh_Hant_TW). - For each tag in order, the candidates language+script+region,
language+script, language+region and language are tried, then the same
for the current code of a deprecated language (
iw->he,in->id,ji->yi,jw->jv,mo->ro); the first supported one wins (pt-PT->pt,zh-Hant-TW->zh_Hant_TW). - Otherwise, for each tag in order, the first supported locale of the same
language wins (
pt->pt_BR,es-MX->es_419). - Otherwise the base locale.
The Dart target leaves this to Flutter: the app's locale is chosen by
Flutter's locale resolution over supportedLocales, and
lookup<Scope>Localization maps it to a class the way gen-l10n does (see
Usage).
Packaging the output for a registry #
The generated code is meant to be wrapped in a package of its own and published to pub.dev, a private pub server, an npm registry or a Python index. The generator writes only the code. You add the package files once, next to it or above it.
Ownership. Each target directory gets a sheety_manifest.json with the
generator version, a hash of the input, the scopes, locales, translation
coverage and the SHA-256 of every file the generator owns. On every run the
generator:
- rewrites only files whose content changed;
- deletes files it generated before that are no longer generated (a removed
sheet or locale). A file edited by hand since is kept instead and is no
longer owned (
modified-generated-filewarning); an edited file that is still generated is overwritten with the same warning; - never touches any other file: a
pubspec.yaml,package.json,pyproject.toml,README.mdorCHANGELOG.mdcan sit in the same directory; - refuses to overwrite a file it does not own (
unowned-file). Without a manifest (first run, or a path that is new to the manifest), an existing file is taken over only when it is identical or carries the whole generated header as comment lines; a takeover that changes the file is reported (took-over-filewarning).
Commit sheety_manifest.json with the code. Its sourceHash and per-locale
coverage are handy in release notes and version checks. The
example/ directory has all three packages below, ready to build.
pub (Flutter package) #
Generate into the package's lib/ (output: lib) and add pubspec.yaml:
name: my_localization
version: 1.4.0
publish_to: https://pub.example.com # your private pub server
environment:
sdk: ^3.6.0
flutter: ">=3.27.0"
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any
Apps import package:my_localization/localization.dart.
npm (TypeScript) #
Generate into src/i18n and compile it to dist with tsc:
{
"name": "@acme/l10n",
"version": "1.4.0",
"type": "module",
"sideEffects": false,
"files": ["dist"],
"exports": {
".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
"./*": { "types": "./dist/*.d.ts", "default": "./dist/*.js" }
},
"scripts": { "prepack": "tsc -p tsconfig.json" },
"devDependencies": { "typescript": "^5.6.0" }
}
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"declaration": true,
"rootDir": "src/i18n",
"outDir": "dist"
},
"include": ["src/i18n/**/*.ts"]
}
"type": "module" is required because the output is ESM. "sideEffects": false
lets bundlers drop unused scopes and locales. Consumers import
@acme/l10n (scopes as namespaces), @acme/l10n/app/eager and
@acme/l10n/meta. Publish with npm publish --registry=https://npm.example.com.
Python (wheel) #
Generate into src/myapp_l10n and add pyproject.toml:
[build-system]
requires = ["setuptools>=69"]
build-backend = "setuptools.build_meta"
[project]
name = "myapp-l10n"
version = "1.4.0"
requires-python = ">=3.9"
dependencies = []
[tool.setuptools.packages.find]
where = ["src"]
[tool.setuptools.package-data]
"*" = ["py.typed"]
Build and upload with python -m build and
twine upload --repository-url https://pypi.example.com dist/*.
CI #
Generation needs only the Dart SDK (no Flutter). A typical job checks that the committed code matches the sheet:
# .github/workflows/l10n.yml
jobs:
l10n:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dart-lang/setup-dart@v1
- run: dart pub global activate sheety_localization 0.7.0-dev
- run: printf '%s' "$GOOGLE_SHEETS_KEY" > credentials.json
env:
GOOGLE_SHEETS_KEY: ${{ secrets.GOOGLE_SHEETS_KEY }}
- run: >
dart pub global run sheety_localization:generate
--check --strict --diagnostics-format=github
--checkwrites nothing. It lists the added (+), changed (~) and removed (-) files and exits with1when the output is stale.dart formatstill runs, so the comparison is stable; use the same--[no-]formatsetting as when generating.--strictturns warnings (missing CLDR plural categories, tag mismatches, unknown locales…) into errors.--diagnostics-format=githubprints::error/::warningannotations (titled with the code and cell, e.g.sheety icu-syntax app!E12) plus the usual text.jsonprints one JSON document on stdout (ok,exitCode,summary,targets,issues,diagnostics, each diagnostic withcode,severity,message,scope,sheet,row,column,locale,key) and logs to stderr, also for a bad command line, configuration or credentials. Annotation paths are relative toGITHUB_WORKSPACE(or the working directory).
Offline / reproducible runs. Save the sheet once, commit the snapshot, and generate from it without credentials:
dart run sheety_localization:generate --sheet=<id> --dump-snapshot=l10n/sheets.json # no target needed
dart run sheety_localization:generate --snapshot=l10n/sheets.json --check
A snapshot is {"sheets": [{"title": "...", "values": [["label", ...], ...]}]}
and contains every sheet, including ignored ones.
Diagnostics #
Every problem has a stable code, so it can be grepped or filtered. Errors stop
generation and nothing is written. Warnings become errors with --strict.
Infos are shown with -v.
| Code | Severity | Meaning |
|---|---|---|
icu-syntax |
error | The cell is not valid ICU (or mustache) within the supported subset, at the reported offset |
plural-missing-other |
error | A plural or select has no other branch |
placeholder-mismatch |
error | A translation uses placeholders the base text does not, or misses one it has |
placeholder-type |
error | A plural count is not int/num, a select choice is not String, or one name is used as both |
select-duplicate-case |
error | A select has the same case twice |
duplicate-label |
error | Two rows have the same key after sanitizing |
duplicate-scope |
error | Two sheets have the same scope name after sanitizing; the second is skipped |
empty-base |
warning | The base-language cell of a row is empty; the message is left out |
unsupported-meta |
error | meta uses DateTime, an unknown type, format, optionalParameters… |
invalid-meta-json |
error | meta is not a JSON object |
reserved-word |
error | A key, placeholder or scope is a reserved word of a target (class, Python def) or a name the generated code uses itself (Dart format, intl, override; TypeScript then; Python get) |
invalid-identifier |
error | A name is not a valid identifier in a target (a key or sheet title starting with a digit, a Dart key starting with an upper-case letter) |
name-collision |
error | Two names collide after case conversion (Python fooBar and foo_bar), or two scopes give the same class or (case-insensitively) directory (rate-us-2 and rate_us2 are both RateUs2Localization) |
plural-missing-category |
warning | A plural lacks a category CLDR requires for the locale (ru needs one few many other); other is used |
plural-exact-as-category |
warning | An exact =0/=1/=2 stands in for zero/one/two, but that category also covers other numbers in the locale (Russian =1{…} without one{…} is also shown for 21, 31…); add the keyword case |
plural-duplicate-case |
warning | A plural has =1 and one (or similar); the later branch wins, as in gen-l10n |
tag-mismatch |
warning | Markup tags differ from the base text or are not balanced |
unused-placeholder |
warning | A placeholder declared in meta is used by no text |
invalid-locale |
warning | A header cell is not a locale code; the column is skipped |
unknown-locale |
warning | A well-formed locale code of an unknown language; the column is kept |
duplicate-locale |
warning | Two header cells denote the same locale; the later column is skipped |
empty-label |
warning | A row has texts but no label; it is skipped |
short-row |
warning | With include_empty: false: a row shorter than the header was skipped |
parent-overridden |
warning | With legacy_regional_override: a regional column overwrote its language's column |
fallback |
info | Messages of a locale use the parent or base text (with counts and keys) |
synthetic-locale |
info | A parent locale (pt) was generated from a regional column (pt_BR) |
not-localization-sheet |
info | A sheet without the localization header is skipped |
empty-row |
info | An empty row is skipped |
non-string-cell |
info | A number or boolean cell was converted to text |
invalid-unicode |
warning | A cell or sheet title contains a lone UTF-16 surrogate; values keep it, comments show U+FFFD |
plural-rules-mismatch |
warning | The Dart target (intl has no rules for the locale) and the TypeScript/Python targets (CLDR) render a plural differently |
Problems outside the sheet are reported with these codes:
| Code | Severity | Meaning |
|---|---|---|
unowned-file |
error | A file not generated by this tool is in the way; move it or choose another output |
invalid-manifest |
error | sheety_manifest.json cannot be read; delete it to let the generator take over again |
foreign-manifest |
error | The sheety_manifest.json in the output belongs to another target (two targets' directories mixed up); nothing is deleted |
case-collision |
error | Two generated paths differ only in case |
path-traversal, duplicate-output |
error | An output path escapes the directory, or is generated twice |
reserved-file-name |
error | A generated path has a segment Windows cannot create (con, nul, com1…, from a sheet title or locale) |
unknown-option, invalid-option |
error | An unknown key under targets.<target>.options, or a value of the wrong type |
no-scopes |
error | A target's filters select no localization sheet |
source-error |
error | The sheet or snapshot cannot be read (error messages never quote the credentials file) |
usage-error, config-error, internal-error |
error | Bad command line, invalid sheety.yaml, or an unexpected failure (exit code 64, 2, 2); also reported in json / github format |
format-failed, emitter-failed, write-failed, snapshot-write |
error | dart format, an emitter, or writing a file failed. Writing is staged (see below), so write-failed says exactly which targets were written |
legacy-output |
warning | First run: files that look generated but are not produced any more (old ARBs, removed scopes). They are left untouched; delete them |
modified-generated-file |
warning | A generated file was edited by hand: a stale one is kept and no longer owned, one that is still generated is overwritten |
took-over-file |
warning | Files without a manifest entry that carried the generated header were taken over and rewritten |
Writing is staged: the new files of every target are first written into a
.sheety-staging-<target> directory inside the target's output directory. Only when
all of them were written are they moved into place, target by target (stale
files are deleted first, the manifest is written last); the staging
directories are then removed. When staging fails, nothing was written. A
failure while moving files into place is rare (a rename on the same file
system); the write-failed message then lists the targets written completely
and the one left partly written (also "partial": true in json), and the
next run repairs it. Deleting before
moving also makes renaming a sheet by case only (chat -> Chat) work on
case-insensitive file systems (macOS, Windows).
Migrating from 0.6.x #
0.7.0-dev no longer writes ARB files or runs flutter gen-l10n. It generates the
same Dart API directly.
Removed options. Each one fails with an explanation (exit code 64):
| 0.6.x | 0.7.0-dev |
|---|---|
--arb, -a |
Removed: no ARB files. Delete the old ARB directory (lib/src/l10n) |
--prefix |
Removed (it named the ARB files) |
--author, --comment, --context |
Removed (ARB metadata). Use --header / header: to put text into every file |
--modified, --[no-]last-modified |
Removed: the output has no timestamps and is deterministic |
Kept. --lib=<dir> and --gen=<subdir> still work. They select the Dart
target with output <dir> (default lib) and the per-scope files under
<subdir> (default src/generated), the same layout as before. They cannot
be combined with --dart. The equivalent sheety.yaml is:
targets:
dart:
output: lib
options: { directory: src/generated, barrel: localization.dart }
--sheet, --credentials, --ignore, --header, --[no-]format and
--[no-]include-empty keep their meaning, but the default of
--include-empty is now on (see below). 0.6.x defaulted --lib to lib;
0.7.0-dev needs a target, so a bare generate --sheet=… now asks for one. Pass
--lib=lib or --dart=lib.
First run over the old output. Without a manifest, files at the generated
paths that carry the generated header are taken over and rewritten. Old ARB
files and the files of scopes that are no longer generated are not
deleted. They are listed in a legacy-output warning; delete them yourself.
From then on the manifest tracks ownership.
Behaviour changes:
- Regional columns. 0.6.x let the first regional column of a language
overwrite the language's own column: real
artexts were replaced byar_EG. Nowarkeeps its texts andar_EGoverrides only its own cells. Synthetic parents (ptfrompt_BR) work as before.--legacy-regional-overriderestores the old behaviour. - Short rows. 0.6.x dropped a row from every locale when the Sheets API
omitted its trailing empty cells, that is, when the last locale column was
empty. Now the missing cells fall back to the parent or base text.
--no-include-emptyrestores the old behaviour. - Duplicate labels used to overwrite each other silently. Now they are an error.
- Stricter ICU. Texts that gen-l10n mis-parsed silently (a stray
},=3{…}) are errors. - Diagnostics. The whole sheet is validated and every problem is reported, instead of failing at the first one inside gen-l10n.
- CI no longer needs Flutter to generate. The app that uses the code still
needs
flutter_localizationsandintl. - New members. The generated classes gain
messages,templates,fallbackKeysandformat(the metadata API).metadata: falseremoves them.
AI-powered localization (localize) #
Besides generating code, Sheety Localization can translate missing cells in your Google Sheet with the OpenAI API and write them back. The service account needs Editor access.
Basic command #
dart pub global run sheety_localization:localize \
--credentials=credentials.json \
--sheet=<YOUR_SPREADSHEET_ID> \
--token=<YOUR_OPENAI_API_KEY> \
--model=gpt-5-mini \
--batch=3 \
--workers=6
Localize option definitions #
--credentials(or-c): Path to your Service Account JSON file. Defaults tocredentials.json.--sheet(or-s) (required): The Google Spreadsheet ID.--token(or-t): OpenAI API key (e.g.sk-...).--token-file(or-f): Path to a file containing the OpenAI API key (alternative to--token).--model(or-m): OpenAI model to use. Defaults togpt-5-mini.--batch(or-b): Number of languages to translate per single API call. Defaults to3. Higher values are faster but may reduce quality for weaker models. Range: 1–20.--workers(or-w): Number of concurrent API requests. Defaults to6, max14.--timeout: Hard timeout of a single OpenAI request, in seconds. Defaults to120, range 10–900. A request that the model never finishes is aborted instead of stalling a worker forever.--ignore(or-i): Comma-separated list of regular expressions — not globs — matched against sheet titles; a sheet whose title matches any of them is skipped (e.g.^help$,^backend,^temp-). The match is unanchored, sobackendalso skipsbackend-billing; anchor with^/$when you want an exact title. A glob-lookingtemp-*means "temp followed by any number of dashes" and will not do what you expect.--prompt(or-p): Path to a custom system prompt file for the AI model.
localize does not read sheety.yaml; pass its options on the command line.
How localization failures are handled #
Only localization sheets are written to. A sheet is localized only when its header matches
label | description | meta | <source> | <locale> ...— that is, when the fourth column is a recognized source language. It does not have to be English:ru,de,pt_BRand any other known language code work just as well, and the rest of the row is translated from that language. Reference tables and notes kept in the same spreadsheet have ordinary data in the fourth column (e.g.Family,Region), which is not a language, so they are skipped with a warning rather than overwritten with translations.--ignoreremains available for sheets that do match the layout but should be left alone anyway.
Language models are unreliable on ambiguous or rare locale codes, so localize defends against that:
- Every locale code is spelled out for the model — name, native endonym and, for codes that are routinely misread, an explicit warning.
ukis sent asuk — Ukrainian (українська) — Ukrainian (Cyrillic script). NOT English and NOT "United Kingdom", so it can no longer come back as English. - A failed batch is split, not retried. If a request for a batch of languages fails — timeout, truncated or invalid JSON, garbage output — the batch is not re-sent as-is. Each language of that batch is retried on its own, so one problematic rare language cannot take its neighbours down with it.
- Every translation is validated before it is written: non-empty, ICU placeholders (
{name}) and markup tags preserved exactly, no leaked markdown fences, no runaway output. An ICU source must give a translation thatgenerate's ICU parser accepts, with every placeholder used the same way (argument, plural or select); a{{name}}source must keep its{{name}}placeholders. A translation that fails validation is retried alone; only that one language is affected. - Partial rows are still saved. Languages that succeeded are written to the sheet even if one of their neighbours never worked; the failed cell stays empty and is picked up on the next run.
Run generate after localize: it validates the new translations as well
(placeholders, plural categories, tags) before any code is produced.
Docker #
A minimal Docker image with AOT-compiled generate and localize binaries is available on DockerHub. No Dart SDK installation required.
Pull #
docker pull plugfox/sheety:latest
Generate localization code #
Mount the project and run from it, so sheety.yaml and its relative paths
resolve:
docker run --rm \
-v "$(pwd):/work" -w /work \
plugfox/sheety:latest \
--config=sheety.yaml \
--no-format
Or without a configuration file:
docker run --rm \
-v "$(pwd)/credentials.json:/credentials.json:ro" \
-v "$(pwd)/lib:/output" \
plugfox/sheety:latest \
--credentials=/credentials.json \
--sheet=<YOUR_SPREADSHEET_ID> \
--dart=/output \
--no-format
Note:
--no-formatis needed inside Docker, becausedart formatis not available in the minimal image. Format the generated Dart files on the host afterwards, and run--checkwith the same setting.
The default entrypoint is /bin/generate.
AI-powered localization (translate missing cells) #
Override the entrypoint to use /bin/localize:
docker run --rm \
--entrypoint /bin/localize \
-v $(pwd)/credentials.json:/credentials.json:ro \
plugfox/sheety:latest \
--credentials=/credentials.json \
--sheet=<YOUR_SPREADSHEET_ID> \
--token=<YOUR_OPENAI_API_KEY> \
--model=gpt-5-mini \
--batch=3 \
--workers=6
Alternatively, pass the API key via a file:
docker run --rm \
--entrypoint /bin/localize \
-v $(pwd)/credentials.json:/credentials.json:ro \
-v $(pwd)/openai_token.txt:/token.txt:ro \
plugfox/sheety:latest \
--credentials=/credentials.json \
--sheet=<YOUR_SPREADSHEET_ID> \
--token-file=/token.txt
Custom system prompt for localization #
docker run --rm \
--entrypoint /bin/localize \
-v $(pwd)/credentials.json:/credentials.json:ro \
-v $(pwd)/my_prompt.txt:/prompt.txt:ro \
plugfox/sheety:latest \
--credentials=/credentials.json \
--sheet=<YOUR_SPREADSHEET_ID> \
--token=<YOUR_OPENAI_API_KEY> \
--prompt=/prompt.txt
Print help #
# generate help
docker run --rm plugfox/sheety --help
# localize help
docker run --rm --entrypoint /bin/localize plugfox/sheety:latest --help
Building the image locally #
# Clone the repository
git clone https://github.com/DoctorinaAI/sheety_localization.git
# Navigate into the project directory
cd sheety_localization
# Local build
docker build -t username/sheety:latest .
# Multi-platform build and push to DockerHub
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t username/sheety:latest \
-t username/sheety:0.7.0-dev \
--push .
Tips #
- Commit the generated code and its
sheety_manifest.json, and run--checkin CI, so a sheet edit can never silently change a release. - Never commit the service account key. Inject it from a CI secret.
- Pin the generator version (
dart pub add --dev sheety_localizationordart pub global activate sheety_localization 0.7.0-dev). The output is deterministic for a given version, but may change between versions. - Keep non-localization tabs (notes, glossaries) in the spreadsheet. They
are skipped automatically, and you can list them in
ignoreto silence the info. - Snapshot before big edits (
--dump-snapshot). A snapshot diff in a pull request shows exactly what translators changed.
Sample VS Code task #
Copy the following into .vscode/tasks.json to run generation from the command palette:
{
"version": "2.0.0",
"tasks": [
{
"label": "Generate Localization",
"type": "shell",
"command": "dart run sheety_localization:generate --config=sheety.yaml",
"options": {
"cwd": "${workspaceFolder}/packages/localization"
},
"problemMatcher": []
}
]
}
- Open Command Palette -> Tasks: Run Task -> Generate Localization.
Example: automatic Google Translate formula #
If you want to auto-fill missing translations from English to Russian:
=IF(ISBLANK(D2), "", GOOGLETRANSLATE(D2, "en", "ru"))
- Place this formula in cell
E2(under therucolumn). - Drag/fill down to apply to all rows.
- Cells with empty
enwill remain blank; otherwise, English text will be machine-translated to Russian.
Example: conditional formatting rules #
-
Gray out machine translations
- Select entire column (e.g., column
Eforru). - Add a custom formula rule:
=ISFORMULA(E2). - Set fill color to light gray.
- Select entire column (e.g., column
-
Highlight empty cells (missing translations)
- Select entire column (e.g.,
E). - Add a custom formula rule:
=E2="". - Set fill color to red (or any noticeable color).
- Select entire column (e.g.,