Terminal
Terminal/Skill
Adds PolyStella to an Astro project so content is translated into other languages at build time, with translations cached in R2.
By Cloudflare
Works with
npx skills add cloudflare/polystella --skill polystella-consumerYou are working in an Astro project that consumes the @cloudflare/polystella-astro
package. This skill covers integration, configuration, common
pitfalls, and the debug flow.
If you are working on the polystella package source itself (adding
adapters, editing translators, modifying the cache layer), STOP and
load polystella-contributor instead.
Build-time content localization for Astro:
.md, .mdx, .toml, .json, .yaml) into additional locales using AI (Workers AI or Anthropic)./[lang]/... for each non-default locale.Astro.locals (t, lhref, getLocalizedEntry, getLocalizedCollection) and React hooks (useTranslations, useLocalizedHref).Visitors get static bytes — no runtime AI calls.
Install from npm:
pnpm add @cloudflare/polystella-astro
The standalone CLI binary is still named polystella.
Peer dependency: astro ^7.0.10.
Set up these four files. The locale set lives in astro.config.mjs
ONLY — everything else derives from it.
astro.config.mjsimport { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";
import polystella, { astroSitemapI18n } from "@cloudflare/polystella-astro";
import polystellaConfig from "./polystella.config.mjs";
// Hoist `i18n` so the same object feeds Astro routing, PolyStella
// translation, AND the sitemap helper. One source of truth.
const i18n = {
defaultLocale: "en-US",
locales: ["en-US", "pt-BR", "ja-JP"],
routing: { prefixDefaultLocale: false },
};
export default defineConfig({
i18n,
integrations: [sitemap(astroSitemapI18n(i18n, { hreflang: { en: "en-US" } })), polystella(polystellaConfig)],
});
polystella.config.mjsWhere provider, glossary, R2, format-specific keys live. The schema source
of truth is packages/astro/src/config/options.ts in the repository;
everything is zod-validated at the boundary.
Skeleton:
import "dotenv/config";
export default {
// R2 config (branch-dispatched — see "Branch-isolated cache" below)
r2: {
accountId: process.env.R2_ACCOUNT_ID,
accessKeyId: process.env.R2_ACCESS_KEY_ID,
secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
bucket: "your-bucket-name",
prefix: "i18n/",
// readOnly: derived from environment; see below
},
provider: {
kind: "workers-ai",
accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
apiToken: process.env.CLOUDFLARE_API_TOKEN,
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
// maxTokens: 8192, // DON'T LOWER — see Pitfall #3
},
// Per-locale model override (optional):
// model: { default: "@cf/meta/...", "ja-JP": "@cf/qwen/..." },
glossaryDir: "i18n/glossary", // YAML files: <locale>.yaml
overridesDir: "i18n/overrides", // <locale>/<mirrored-path>
// Translatable frontmatter keys per source glob:
frontmatter: {
"content/publications/**/*.md": ["title", "description"],
"content/people/**/*.md": ["position", "bio"],
},
// Per-batch document-context framing (improves cross-section consistency):
markdown: {
contextKeys: {
"content/publications/**/*.md": ["title", "excerpt"],
},
},
// Locale-prefixed routes — list any pages that need shimming:
routes: [
"src/pages/index.astro",
"src/pages/[slug].astro",
// { source: "src/pages/[slug].astro", imports: ["./src/styles/publication.css"] },
],
// CSS imports for shims (see Pitfall #5):
routesImports: ["./src/styles/global.css"],
};
src/content.config.tsimport { defineCollection } from "astro:content";
import { polystellaCollections } from "@cloudflare/polystella-astro/content";
import { i18nLoader, i18nSchema } from "@cloudflare/polystella-astro/i18n";
import { publications, people } from "./content-schemas";
export const collections = {
...polystellaCollections({
source: { publications, people },
}),
// Hand-authored UI-strings collection, drift-detected at build:
i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};
src/env.d.ts/// <reference types="@cloudflare/polystella-astro/client" />
Picks up types for PolyStella's virtual modules (polystella:runtime-config).
Use the lower-level packages when Astro should not own the operation:
source/record -> adapter -> core -> provider -> core -> adapter -> output
PermanentProviderError from @cloudflare/polystella-core.@cloudflare/polystella-core/adapters.@cloudflare/polystella-core/providers or its provider subpaths.These packages use standard Web APIs and run in Workers without
nodejs_compat; enabling nodejs_compat is also supported. The Astro
package has no compatibility shims for low-level imports that moved to
these owners.
Chrome text (nav, footer, accessibility strings) lives in
src/content/i18n/<locale>.json as flat key→string dicts. The
default-locale file is the single source of truth; non-default
locales must match its key set.
Workflow:
src/content/i18n/en-US.json — add, remove, or change keys.polystella translate-ui to propagate changes through other locales.polystella check-ui automatically when src/content/i18n/ is staged.Wire the pre-commit hook (.githooks/pre-commit):
if printf '%s\n' "$STAGED" | grep -qE '^src/content/i18n/'; then
pnpm exec polystella check-ui
fi
Use this path when a project wants PolyStella's JSON catalog flow but already owns content localization, routing, or collection lookups. It does not register translated content collections, route shims, R2 cache clients, or localized collection APIs.
Astro integration:
import { defineConfig } from "astro/config";
import catalogAstro from "@cloudflare/polystella-astro/catalog/astro";
export default defineConfig({
i18n: {
defaultLocale: "en-US",
locales: ["en-US", "pt-BR", "ja-JP"],
},
integrations: [
catalogAstro({
baseDir: "./src/i18n",
middleware: true,
driftCheck: true,
}),
],
});
Manual middleware with explicit dictionaries:
import { catalogMiddleware } from "@cloudflare/polystella-astro/catalog/middleware";
export const onRequest = catalogMiddleware({
defaultLocale: "en-US",
locales: ["en-US", "pt-BR"],
getDictionary: async (locale) => {
if (locale === "en-US") return (await import("./i18n/en-US.json")).default;
if (locale === "pt-BR") return (await import("./i18n/pt-BR.json")).default;
return undefined;
},
});
The catalog middleware binds only Astro.locals.t and
Astro.locals.lhref. The CLI commands still apply; use --base if the
catalog directory is not ./src/content/i18n:
polystella check-ui --base ./src/i18n
polystella sync-ui --base ./src/i18n
polystella translate-ui --base ./src/i18n
Catalog files accept two formats, auto-detected per file (all locale files must use the same format):
Flat — { "site.title": "Cloudflare Blog" }.
Nested — groups flattened to the same dotted keys, so t("site.title")
works identically in both formats:
{
"site": {
"i18n_group_title": "Site",
"title": "Cloudflare Blog"
}
}
i18n_group_title is optional per-group metadata for tooling that
reads the JSON; it is excluded from t() keys, drift checks, and AI
translation.
In .astro files:
---
const { t, lhref, getLocalizedEntry, getLocalizedCollection } = Astro.locals;
const { slug } = Astro.params;
const entry = await getLocalizedEntry("publications", slug);
const activePeople = await getLocalizedCollection(
"people",
({ data }) => data.type === "active",
);
---
<a href={lhref("/foo")}>{t("nav.foo")}</a>
Outside .astro (utility scripts, getStaticPaths, React islands):
import { getLocalizedEntry, getLocalizedCollection, localizedHref } from "@cloudflare/polystella-astro/runtime";
import { useTranslations, useLocalizedHref } from "@cloudflare/polystella-astro/react";
import { getDictionary } from "@cloudflare/polystella-astro/i18n";
Three modes, dispatched automatically by polystella.config.mjs:
| Mode | Env signals | r2.prefix | Writes? |
|---|---|---|---|
| Local build | neither var set | i18n/ (read-only against main) | NO |
| CI build (main) | WORKERS_CI_BRANCH=main | i18n/ | YES |
| CI build (preview) | WORKERS_CI_BRANCH=<other> | previews/<branch>/i18n/ + fallback | YES (preview prefix only) |
| Explicit CLI | POLYSTELLA_CLI=1 (set by cli.ts) | per resolved branch | YES |
Key mental model: a developer's local pnpm build can NEVER overwrite production. To populate R2 from outside CI, use the explicit polystella translate CLI.
Configure a lifecycle rule on the R2 bucket to expire previews/* after 30 days. The package only prunes within its configured prefix, so cross-build cleanup of orphan preview prefixes needs the lifecycle rule.
Drop a file at i18n/overrides/{locale}/<mirrored-path> and it wins over AI output verbatim. Overrides go through the URL rewriter (idempotent) but are NOT written to R2 — they live in your repo, not in the cache.
Use overrides for content you want to control exactly (legal copy, brand names, marketing taglines).
Configure one per-locale YAML source using glossary.file,
glossary.http, glossary.r2, or glossary.inline. File paths, HTTP
URLs, and R2 keys use {locale}; PolyStella loads one object per target
locale. See the glossary concept guide for the YAML shape and private
repository examples.
Editing a glossary changes that locale's glossary hash and re-translates the whole corpus for that locale.
After every translation pass, astro build (and polystella translate) writes dist/i18n-r2-report.json with per-pair outcomes: cache hits, AI translations, overrides, errors, locally-skipped pairs, prune actions. Check it when something looks wrong.
astro.config.mjs's i18n.locales is the only source of truth. Don't duplicate it in polystella.config.mjs. The astroSitemapI18n(i18n, ...) helper takes the same i18n block. Sitemap config that doesn't match Astro's i18n ships locale-prefixed URLs with no hreflang annotations — search engines treat them as duplicate content.previews/<branch>/i18n/, initially empty. The fallback to i18n/ means cache hits still come from main; new translations write to the preview prefix. This is correct behaviour.maxTokens default — The schema default is 8192. Lowering it truncates multi-segment translations into invalid JSON. Keep it at 8192 unless you've measured single-segment files and know what you're doing.pnpm i18n:sync alone is not enough — Sync only reconciles keys; it leaves new keys as "" placeholders. The build's drift check fails on "" in a non-default locale when the source value is non-empty. Run pnpm i18n:translate (or hand-edit) to fill placeholders before committing.<SourcePage /> components. List your global CSS in routesImports (or per-route via the object form) so shims emit the import directly.prettier --write collapses sync writer's blank lines — The UI-string sync writer preserves blank-line section breaks between key groups. prettier --write collapses them. The pre-commit hook should use prettier --check (not --write).{{token}} placeholders dropped by AI — Validated post-translation; if a token is missing or renamed after all retries, the key is left empty for manual fix-up. Hand-edit the locale JSON in that case..mdx uses MDX syntax rules (imports/exports, JSX, expressions); .md stays plain Markdown. If your .md files use Markdown-only constructs, don't accidentally rename them to .mdx..env (gitignored) + dotenv/config at the top of polystella.config.mjs. Workers Builds inject credentials via env vars; local development reads from .env.polystella translate # translate for current git branch
polystella translate --branch main # target main's R2 prefix explicitly
polystella translate --locale pt-BR # one locale only
polystella translate --file 'foo.md' # one file
polystella translate --dry-run # plan only, no provider/R2 calls
polystella translate --prefix 'custom/i18n/' # direct r2.prefix override
polystella check-ui # drift detection (offline)
polystella sync-ui # reconcile key sets (offline)
polystella sync-ui --check # dry-run sync, exits non-zero if work pending
polystella translate-ui # sync + AI-fill empty placeholders
polystella translate-ui --locale pt-BR # one locale only
polystella translate-ui --sync-only # same as `sync-ui`
Exit codes: 0 clean, 1 config error, 2 translation/sync work failed.
Typical host-project package.json wrappers:
{
"scripts": {
"translate": "polystella translate",
"translate:dry": "polystella translate --dry-run",
"i18n:check": "polystella check-ui",
"i18n:sync": "polystella sync-ui",
"i18n:translate": "polystella translate-ui"
}
}
When a translation is wrong:
polystella translate --dry-run --file '<source-path>' to see the planned R2 key. Verify the key is what you expect.<root>/.astro/i18n-staging/<locale>/<source-path>. Did the AI output land there? Is the marker (aiTranslated: true) in the frontmatter?dist/i18n-r2-report.json) — was it a hit, miss, override, or error?cat <glossaryDir>/<locale>.yaml and confirm the term is listed.i18n/overrides/<locale>/<exact-mirror-of-source> exists.LOG_LEVEL=debug polystella translate --file '...' for batch-level detail (segment count, batch count, oversize warnings).<root>/.astro/i18n-staging/.polystella-cache.json.pnpm i18n:sync and commit without pnpm i18n:translate — the build will fail on empty placeholders.POLYSTELLA_CLI=1 (the CLI does this automatically; this is a warning if you're scripting against the R2 client directly).astro:config:setup — sibling collections will see empty staging dirs.astro.config.mjs i18n block is the single source of truth.| You want to | Look at |
|---|---|
| Understand the system | https://github.com/cloudflare/polystella/blob/main/ARCHITECTURE.md |
| See config schema | node_modules/@cloudflare/polystella-astro/src/config/options.ts |
| See available exports | Each installed @cloudflare/polystella* package manifest |
| See CLI flags | polystella --help, polystella <subcommand> --help |
| Debug a translation | dist/i18n-r2-report.json, <root>/.astro/i18n-staging/<locale>/... |
| File an issue | https://github.com/cloudflare/polystella/issues |