Website: multilingual site (12 languages) with staged rollout

.github/workflows/ci.yml

@@ -133,7 +133,10 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
+      # Previews build every language, including those not live yet (website/src/i18n/locales.ts).
       - run: npm run website:build
+        env:
+          I18N_PREVIEW: '1'
       # Keep previews out of search engines.
       - run: |
           printf '\n/*\n  X-Robots-Tag: noindex\n' >> website/dist/_headers

website/astro.config.ts

@@ -1,3 +1,4 @@
+import { satteri } from '@astrojs/markdown-satteri';
 import react from '@astrojs/react';
 import tailwindcss from '@tailwindcss/vite';
 import { defineConfig } from 'astro/config';
@@ -9,12 +10,16 @@ export default defineConfig({
   // The site's own URL: canonical links, sitemap and the file URLs in icons.json and the registry.
   site: process.env.SITE_URL ?? 'https://useanimations.com',
   output: 'static',
+  // A separate output folder, e.g. for builds running side by side: ASTRO_OUT_DIR=/tmp/dist-a
+  ...(process.env.ASTRO_OUT_DIR ? { outDir: process.env.ASTRO_OUT_DIR } : {}),
   // Pages are written as documentation.html, so hosts serve /documentation without a trailing slash,
   // matching the canonical URLs and the previous site.
   trailingSlash: 'never',
   build: { format: 'file' },
   integrations: [react()],
   markdown: {
+    // `## Überschrift {#english-id}`: translated documentation keeps the English heading ids.
+    processor: satteri({ features: { headingAttributes: true } }),
     // The same themes as lib/highlight.ts.
     shikiConfig: {
       themes: { light: 'github-light-high-contrast', dark: 'github-dark-dimmed' },

website/package.json

@@ -8,6 +8,7 @@
     "preview": "astro preview"
   },
   "dependencies": {
+    "@astrojs/markdown-satteri": "0.4.3",
     "@astrojs/react": "^7.0.1",
     "@fontsource-variable/geist": "^5.3.0",
     "@fontsource-variable/geist-mono": "^5.3.0",

website/public/flags/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Panayiotis Lipiridis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

website/src/components/Breadcrumbs.astro

@@ -4,12 +4,14 @@ import type { Crumb } from '../lib/hubs';
 interface Props {
   /** Every level, the current page last. */
   crumbs: Crumb[];
+  /** Accessible name of the trail, in the page's language. */
+  label?: string;
 }
 
-const { crumbs } = Astro.props;
+const { crumbs, label = 'Breadcrumb' } = Astro.props;
 ---
 
-<nav aria-label="Breadcrumb" class="text-sm text-muted">
+<nav aria-label={label} class="text-sm text-muted">
   {
     crumbs.map((crumb, index) =>
       index < crumbs.length - 1 ? (

website/src/components/CodeBlock.astro

@@ -1,4 +1,5 @@
 ---
+import { EN, type Locale, t } from '../i18n';
 import { highlight } from '../lib/highlight';
 
 interface Props {
@@ -8,8 +9,10 @@ interface Props {
   class?: string;
   /** Event data for the copy button, e.g. { icon, code } (scripts/analytics.ts). */
   track?: Record<string, string>;
+  /** Language of the button text. */
+  locale?: Locale;
 }
-const { code, lang, label, class: className, track = { code: lang } } = Astro.props;
+const { code, lang, label, class: className, track = { code: lang }, locale = EN } = Astro.props;
 const trackData = Object.fromEntries(Object.entries(track).map(([key, value]) => [`data-track-${key}`, value]));
 const html = await highlight(code, lang);
 ---
@@ -23,6 +26,6 @@ const html = await highlight(code, lang);
     data-track="copy"
     {...trackData}
     class="absolute top-2 right-2 rounded-lg border border-line bg-surface px-2 py-1 text-xs text-muted opacity-0 transition group-hover/code:opacity-100 focus:opacity-100 data-[copied]:text-accent"
-    ><span data-copy-label>Copy</span></button
+    ><span data-copy-label>{t(locale).common.copy}</span></button
   >
 </div>

website/src/components/FaqList.astro

@@ -4,13 +4,15 @@ import type { Faq } from '../lib/seo';
 interface Props {
   faq: Faq;
   class?: string;
+  /** Heading, in the page's language. */
+  title?: string;
 }
 
-const { faq, class: className } = Astro.props;
+const { faq, class: className, title = 'FAQ' } = Astro.props;
 ---
 
 <section class:list={['max-w-3xl', className]} aria-labelledby="faq-title">
-  <h2 id="faq-title" class="text-2xl font-semibold tracking-tight">FAQ</h2>
+  <h2 id="faq-title" class="text-2xl font-semibold tracking-tight">{title}</h2>
   <div class="mt-5 divide-y divide-line rounded-3xl border border-line">
     {
       faq.map(({ question, answer }) => (