Skip to content

v1.0.0-beta.2 — hash-bucketed catalog layout

Pre-release
Pre-release

Choose a tag to compare

View all tags
@tamimbinhakim tamimbinhakim released this 29 Apr 05:35
v1.0.0-beta.2
66f12f2

What's new

Replaces the source-tree-mirroring chunk layout with a flat hash-bucketed shape. Same key always lands in the same bucket across every locale; same model as the maintainer's earlier ai18n design plus chunking.

On-disk layout

.translations/
  en/   0.json … f.json     # 16 buckets, name = first hex digit of key hash
  es/   0.json … f.json     # mirror — same keys, translated values
  .meta.json

Catalog keys

12-char SHA-256 prefixes replace literal source strings. Plain-string useT('Sign out') calls hash internally — users still write the literal source. <T> blocks already used t.<hash> keys; those persist with the same shape.

Wins

  • Smaller PR diffs — one string changed → one bucket file changes per locale (vs. one giant file or one-per-source-tree).
  • Cross-locale alignment is structural — hash is content-addressed.
  • Better tree-shaking — each bucket is an independent JSON import.
  • Smaller edge runtime payloads — fetch only buckets a route touches.
  • Auto-migration on read — runtime loaders and the CLI catalog reader transparently rekey old literal-keyed catalogs into the new hashed layout.

New public API

  • sourceKey(literal, context?) — produce the catalog storage key.
  • buildCatalog(entries) — hash-key a literal-keyed object (tests, programmatic overrides, hand-rolled fixtures).

New CLI command

npx autotranslate migrate-format

Forces every locale through the writer — useful when migrating in CI without a translate run. Drops the legacy provider cache.

Tunable

defineConfig({
  catalog: {
    chunkBits: 4, // default — 16 buckets. Range 0..12.
  },
});

Trade-off

Translator hot path adds one SHA-256 of the literal key per t() call: ~1.1µs/call (was 0.4µs). Still ~50× under the published <50µs/call target.

Packages

Package Version
@autotranslate/core 1.0.0-beta.2
@autotranslate/cli 1.0.0-beta.2
@autotranslate/react 1.0.0-beta.2
@autotranslate/next 1.0.0-beta.2
@autotranslate/vite 1.0.0-beta.2
@autotranslate/providers 1.0.0-beta.2
@autotranslate/eslint-plugin 1.0.0-beta.2
@autotranslate/experiments 1.0.0-beta.2
@autotranslate/zod 1.0.0-beta.2
@autotranslate/typescript-plugin 1.0.0-beta.1 
pnpm add @autotranslate/core@beta @autotranslate/react@beta
pnpm add -D @autotranslate/cli@beta
Assets 2
Loading