DEV Community: Mariana Bravo

Que tu build de Astro falle si falta una traducción

Mariana Bravo — Fri, 09 Oct 2026 21:37:03 +0000

English version: Make missing translations fail your Astro build

Hago sitios para clientes que necesitan inglés y español. El error que se me
escapaba una y otra vez era siempre el mismo: alguien agrega un texto en
inglés, nadie lo traduce, y semanas después lo descubre un visitante que
habla español. Casi siempre es el segundo idioma el que se rompe en silencio.

El enrutamiento i18n de Astro te da / y /es/, hreflang y URLs por idioma.
Lo que no te dice es que a tu página en español le falta un testimonio, o que
la tabla de precios en español todavía dice $29 después de que subiste el
precio a $39.

Así que convertí esos desajustes en un error de compilación. Son tres
comprobaciones, con Astro y TypeScript puros, sin librerías.

1. Textos tipados: si falta una clave, no compila

Pon todo el texto fijo del sitio —menú, hero, botones, metadatos— en dos
archivos de TypeScript, y deriva el tipo del archivo en inglés:

// src/content/copy.en.ts
export const COPY_EN = {
  hero: {
    title: 'Launch in English and Spanish on day one.',
    cta: 'Get early access',
  },
  features: [
    { title: 'Two languages, one deploy', body: '…' },
    // …
  ],
};

export type SiteCopy = typeof COPY_EN;

// src/content/copy.es.ts
import type { SiteCopy } from './copy.en';

export const COPY_ES = {
  hero: {
    title: 'Lanza en español e inglés desde el primer día.',
    cta: 'Quiero acceso anticipado',
  },
  features: [
    { title: 'Dos idiomas, un despliegue', body: '…' },
    // …
  ],
} satisfies SiteCopy;

La clave es satisfies. Si borras hero.cta del archivo en español,
astro check falla, y tu editor lo marca antes de que guardes. Si agregas una
clave que el inglés no tiene, también falla, así que los dos archivos no
pueden separarse en silencio en ninguna dirección.

2. Misma cantidad en ambos idiomas: lo que `satisfies` no ve

satisfies revisa la forma, no la longitud. Seis funciones en inglés y cinco
en español cumplen igual con { title: string; body: string }[]. Y ese es el
desajuste más común de todos: alguien agrega un testimonio en un solo idioma.

Un recorrido recursivo pequeño lo detecta:

// src/lib/copy-parity.ts
export function assertCopyParity(en: unknown, es: unknown, path = ''): void {
  if (Array.isArray(en) && Array.isArray(es)) {
    if (en.length !== es.length) {
      throw new Error(
        `copy: "${path}" has ${en.length} entries in English but ${es.length} in Spanish — ` +
          `arrays must have the same length in both locales.`,
      );
    }
    en.forEach((item, i) => assertCopyParity(item, es[i], `${path}[${i}]`));
    return;
  }
  if (en && typeof en === 'object' && es && typeof es === 'object') {
    for (const key of Object.keys(en)) {
      assertCopyParity(
        (en as Record<string, unknown>)[key],
        (es as Record<string, unknown>)[key],
        path ? `${path}.${key}` : key,
      );
    }
  }
}

Llámala al cargar el módulo, en el único archivo que todas las páginas
importan para obtener los textos, no dentro de una página:

// src/content/copy.ts
import { assertCopyParity } from '../lib/copy-parity';
import { COPY_EN, type SiteCopy } from './copy.en';
import { COPY_ES } from './copy.es';

assertCopyParity(COPY_EN, COPY_ES); // se ejecuta en cada build

export function copyFor(locale: 'en' | 'es'): SiteCopy {
  return locale === 'es' ? COPY_ES : COPY_EN;
}

Como se ejecuta al cargar el módulo, salta en cada astro build, sin
importar qué página importe copyFor primero. Y el error es concreto:

Error: copy: "features" has 6 entries in English but 5 in Spanish —
arrays must have the same length in both locales.

3. Contenido en pares: la misma entrada, dos archivos

El contenido más largo —planes de precios, preguntas frecuentes, áreas de
práctica— vive en colecciones de contenido Markdown, en pares de archivos:

src/content/plans/
  starter.md      starter.es.md
  pro.md          pro.es.md
  scale.md        scale.es.md

Aquí pueden fallar dos cosas. Puede faltar el archivo par, o un campo que
debe ser idéntico en ambos idiomas —el precio, el orden— puede cambiar en un
solo archivo. Lo segundo es traicionero, porque en una revisión de código
nunca ves los dos idiomas en la misma pantalla.

Empareja las entradas por nombre de archivo y compara los campos que no deben
diferir:

// src/lib/pairs.ts
export function pairByLocale<T>(entries: { id: string; data: T }[], collection: string) {
  const en = new Map<string, T>();
  const es = new Map<string, T>();
  for (const { id, data } of entries) {
    if (id.endsWith('.es')) es.set(id.slice(0, -3), data);
    else en.set(id, data);
  }
  for (const key of en.keys())
    if (!es.has(key))
      throw new Error(`${collection}: "${key}" has no Spanish counterpart — expected src/content/${collection}/${key}.es.md to exist.`);
  for (const key of es.keys())
    if (!en.has(key))
      throw new Error(`${collection}: "${key}.es" has no English counterpart — expected src/content/${collection}/${key}.md to exist.`);
  return [...en].map(([key, data]) => ({ key, en: data, es: es.get(key)! }));
}

export function assertPairedFields<T>(
  pairs: { key: string; en: T; es: T }[],
  fields: readonly (keyof T)[],
  collection: string,
) {
  for (const pair of pairs)
    for (const field of fields)
      if (pair.en[field] !== pair.es[field])
        throw new Error(
          `${collection}: "${pair.key}" field "${String(field)}" differs across locales — ` +
            `EN=${JSON.stringify(pair.en[field])}, ES=${JSON.stringify(pair.es[field])}.`,
        );
}

// src/lib/content.ts
import { getCollection } from 'astro:content';
import { assertPairedFields, pairByLocale } from './pairs';

// Todo lo que no es texto traducido.
const PAIRED_PLAN_FIELDS = ['priceMonthly', 'priceYearly', 'featured', 'order'] as const;

export async function getPlanPairs() {
  const pairs = pairByLocale(await getCollection('plans'), 'plans');
  assertPairedFields(pairs, PAIRED_PLAN_FIELDS, 'plans');
  return pairs.sort((a, b) => a.en.order - b.en.order);
}

Ahora, si subes el precio del plan Pro en pro.md y olvidas pro.es.md,
obtienes:

Error: plans: "pro" field "priceMonthly" differs across locales — EN=39, ES=29.

La trampa que rompe el emparejamiento sin avisar

Esta me costó una tarde. El loader glob() de Astro genera los ids de las
entradas convirtiendo la ruta del archivo en slug, y al hacerlo elimina el
punto: pro.es.md termina con el id proes. El sufijo .es desaparece, y
el código de emparejamiento cree que proes es otra entrada en inglés sin su
par en español.

Genera el id a partir del nombre del archivo tú mismo:

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const fromFilename = ({ entry }: { entry: string }) => entry.replace(/\.md$/, '');

const plans = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/plans', generateId: fromFilename }),
  // schema: …
});

Lo mismo pasa si tu frontmatter tiene un campo slug: el generateId por
defecto lo usa, así que un par EN/ES que comparte slug se colapsa en una sola
entrada.

Qué ganas con esto

astro check falla si falta una clave.
astro build falla si falta un elemento en una lista, si falta el archivo par, o si un valor cambió en un solo idioma.
Cada error dice exactamente qué ruta o archivo corregir.
Nada de esto llega al navegador: todo corre al compilar.

Son menos de 100 líneas en total, y sirve para cualquier cantidad de idiomas
si generalizas el par en/es a un mapa.

Empaqueté este enfoque en dos plantillas bilingües con Astro 7 y Tailwind 4:
Despega, una landing para SaaS, y
Despacho, para despachos y servicios
profesionales. Son de pago ($79 / $59, pago único, proyectos ilimitados) en
templates.bravelytech.com, pero todo
lo de arriba lo puedes usar en cualquier proyecto.

¿Cómo mantienes sincronizados los idiomas en tus sitios multilingües? Me
interesa saber cómo lo resuelven otros.

Make missing translations fail your Astro build

Mariana Bravo — Fri, 09 Oct 2026 19:27:49 +0000

Versión en español: Que tu build de Astro falle si falta una traducción

I build sites for clients who need English and Spanish. The bug I kept
shipping was always the same one: someone adds a string in English, nobody
translates it, and a Spanish-speaking visitor finds the gap weeks later. It is
almost always the second language that quietly breaks.

Astro's i18n routing gives you / and /es/, hreflang and locale-aware
URLs. It does not tell you that your Spanish page is missing a testimonial,
or that the Spanish pricing table still says $29 after you raised it to $39.

So I made drift a build error. Three checks, plain Astro and TypeScript, no
libraries.

1. Typed copy: a missing key is a compile error

Put every piece of one-off text — nav labels, hero, CTAs, meta — in two
TypeScript files, and derive the type from the English one:

// src/content/copy.en.ts
export const COPY_EN = {
  hero: {
    title: 'Launch in English and Spanish on day one.',
    cta: 'Get early access',
  },
  features: [
    { title: 'Two languages, one deploy', body: '…' },
    // …
  ],
};

export type SiteCopy = typeof COPY_EN;

// src/content/copy.es.ts
import type { SiteCopy } from './copy.en';

export const COPY_ES = {
  hero: {
    title: 'Lanza en español e inglés desde el primer día.',
    cta: 'Quiero acceso anticipado',
  },
  features: [
    { title: 'Dos idiomas, un despliegue', body: '…' },
    // …
  ],
} satisfies SiteCopy;

satisfies is the important part. Delete hero.cta from the Spanish file and
astro check fails — your editor flags it before you even save. Add a key
that English doesn't have and that fails too, so the two files can't quietly
grow apart in either direction.

2. Array parity: what `satisfies` can't see

satisfies checks shape, not length. Six English features and five Spanish
ones both satisfy { title: string; body: string }[]. That's the most common
drift of all: someone adds a testimonial in one language.

A small recursive walk catches it:

// src/lib/copy-parity.ts
export function assertCopyParity(en: unknown, es: unknown, path = ''): void {
  if (Array.isArray(en) && Array.isArray(es)) {
    if (en.length !== es.length) {
      throw new Error(
        `copy: "${path}" has ${en.length} entries in English but ${es.length} in Spanish — ` +
          `arrays must have the same length in both locales.`,
      );
    }
    en.forEach((item, i) => assertCopyParity(item, es[i], `${path}[${i}]`));
    return;
  }
  if (en && typeof en === 'object' && es && typeof es === 'object') {
    for (const key of Object.keys(en)) {
      assertCopyParity(
        (en as Record<string, unknown>)[key],
        (es as Record<string, unknown>)[key],
        path ? `${path}.${key}` : key,
      );
    }
  }
}

Call it at module load, in the one file every page imports to get copy,
not inside a page:

// src/content/copy.ts
import { assertCopyParity } from '../lib/copy-parity';
import { COPY_EN, type SiteCopy } from './copy.en';
import { COPY_ES } from './copy.es';

assertCopyParity(COPY_EN, COPY_ES); // runs on every build

export function copyFor(locale: 'en' | 'es'): SiteCopy {
  return locale === 'es' ? COPY_ES : COPY_EN;
}

Because it runs when the module loads, it fires on every astro build, no
matter which page happens to import copyFor first. The failure is
specific:

Error: copy: "features" has 6 entries in English but 5 in Spanish —
arrays must have the same length in both locales.

3. Content-collection pairs: same entry, two files

Longer content — pricing plans, FAQ answers, practice areas — lives in
Markdown content collections as file pairs:

src/content/plans/
  starter.md      starter.es.md
  pro.md          pro.es.md
  scale.md        scale.es.md

Two things can drift here. A file can be missing its counterpart, and a field
that must be identical in both languages — the price, the sort order — can
change in one file only. That second one is nasty, because you never see both
languages on one screen in code review.

Pair the entries by filename, then compare the fields that must not differ:

// src/lib/pairs.ts
export function pairByLocale<T>(entries: { id: string; data: T }[], collection: string) {
  const en = new Map<string, T>();
  const es = new Map<string, T>();
  for (const { id, data } of entries) {
    if (id.endsWith('.es')) es.set(id.slice(0, -3), data);
    else en.set(id, data);
  }
  for (const key of en.keys())
    if (!es.has(key))
      throw new Error(`${collection}: "${key}" has no Spanish counterpart — expected src/content/${collection}/${key}.es.md to exist.`);
  for (const key of es.keys())
    if (!en.has(key))
      throw new Error(`${collection}: "${key}.es" has no English counterpart — expected src/content/${collection}/${key}.md to exist.`);
  return [...en].map(([key, data]) => ({ key, en: data, es: es.get(key)! }));
}

export function assertPairedFields<T>(
  pairs: { key: string; en: T; es: T }[],
  fields: readonly (keyof T)[],
  collection: string,
) {
  for (const pair of pairs)
    for (const field of fields)
      if (pair.en[field] !== pair.es[field])
        throw new Error(
          `${collection}: "${pair.key}" field "${String(field)}" differs across locales — ` +
            `EN=${JSON.stringify(pair.en[field])}, ES=${JSON.stringify(pair.es[field])}.`,
        );
}

// src/lib/content.ts
import { getCollection } from 'astro:content';
import { assertPairedFields, pairByLocale } from './pairs';

// Everything that is not translated copy.
const PAIRED_PLAN_FIELDS = ['priceMonthly', 'priceYearly', 'featured', 'order'] as const;

export async function getPlanPairs() {
  const pairs = pairByLocale(await getCollection('plans'), 'plans');
  assertPairedFields(pairs, PAIRED_PLAN_FIELDS, 'plans');
  return pairs.sort((a, b) => a.en.order - b.en.order);
}

Now raising the Pro price in pro.md and forgetting pro.es.md gives you:

Error: plans: "pro" field "priceMonthly" differs across locales — EN=39, ES=29.

The gotcha that silently breaks pairing

This one cost me an afternoon. Astro's glob() loader generates entry ids by
slugifying the file path, and slugifying strips the dot: pro.es.md
becomes the id proes. The .es suffix is gone, so the pairing code thinks
proes is a separate English entry with no Spanish counterpart.

Derive the id from the filename yourself:

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const fromFilename = ({ entry }: { entry: string }) => entry.replace(/\.md$/, '');

const plans = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/plans', generateId: fromFilename }),
  // schema: …
});

The same trap applies if your frontmatter has a slug field: the default
generateId uses it, so an EN/ES pair that shares a slug collapses into one
entry.

What this buys you

astro check fails on a missing key.
astro build fails on a missing array item, a missing counterpart file, or a value that drifted between languages.
Every error names the exact path or file to fix.
None of it ships to the browser — it all runs at build time.

It's under 100 lines in total, and it works for any number of locales if
you generalise the en/es pair to a map.

I packaged this approach into two bilingual Astro 7 + Tailwind 4 templates:
Despega, a SaaS landing page, and
Despacho, for law firms and
professional services. They're paid ($79 / $59, one-time, unlimited
projects) at templates.bravelytech.com,
but everything above is yours to use in any project.

How do you keep locales in sync on your multilingual sites? I'd like to hear
what other people do.