DEV Community: Lumora

The value was in nine places and one enum, and the enum was the only one that ran

Lumora — Sat, 15 Aug 2026 05:09:42 +0000

You add a value to a feature. It goes into the type union, into the metadata map the create form renders from, into the access table, into the shelf that decides what appears on the landing pages, into the sitemap. You write sample content for it. You run the suite. Green. Then someone opens the site, picks the new option, and the request comes back 400 Invalid input — every time, for everybody, all day.

The value was birthday, a seventh theme for a picture-book generator. The thing that rejected it was one hand-written schema inside the route:

// POST /api/generate
theme: z.enum(["bedtime", "adventure", "fantasy", "friendship", "wisdom", "learning"]),

Six literals, typed out by hand months earlier. The selector offered a seventh. The gate had never heard of it.

Why a full day of work never touched it

Every book generated that day came out of a script that called insertStory directly and pushed the job onto the queue. Six books, six good renders, six sets of illustrations we sat and reviewed. None of them went through POST /api/generate, because the script did not need to. The unit suite did not go through it either — by design it runs with no database and no network, so it never loads that route.

So the pipeline was fine. Generation was fine. The prompts, the wardrobe rules, the visual notes, all fine. The one edge nobody exercised was the door the product actually opens.

The gap has a name worth keeping: the pipeline works and the product works are two different claims, and testing the back half proves only the first. It surfaced from the site, not from the suite.

Grep found five more copies of the same six strings

The literal list had been copy-pasted around:

api/internal/stories/seed: same six, same omission
admin/stories: the back-office filter could not find a birthday story at all
a dev-only loading preview: harmless, drifting anyway
lib/seo/landingCatalog: the comment above it read "themes that ship today", and it listed six. Every generated landing page had been silently skipping the new theme
tests/landingCombos.test.ts: the worst one

That last file asserts that every landing combination uses a valid theme, and it carries its own definition of "valid": the stale six. So while the theme was broken, the test was green. Fix the omission and add birthday combos, and the test goes red. A test that passes because reality has not reached it yet, and fails the moment it does.

The pattern was already in the same file, two lines down

theme: z.enum([...six literals...]),
language: z.enum(STORY_INPUT_LANGUAGES),   // derived, so the API gate cannot drift from the create form

Somebody had already hit this, written the fix, written the comment explaining it, and applied it to exactly one field. The repair was to derive STORY_THEMES from the metadata map the create form already renders, import it everywhere, and add a test that scans src/ and fails any file quoting three or more theme literals in a row.

Curated subsets are the awkward part. The age-band recommendations and the random default pool on the create page genuinely should not grow every time a theme ships. Those now carry a THEME-SUBSET: marker saying why they are a subset — because without it, deliberate and forgot are byte-for-byte identical in a diff, which is the whole reason this shipped broken.

The check that would have caught it takes three requests

Not one. Three, sent through the front door with a control group:

theme=birthday  -> 403 premium_theme    the thing being fixed
theme=wisdom    -> 403 premium_theme    positive control: a theme known to work
theme=nonsense  -> 400 Invalid input    negative control: the gate still rejects junk

Read alone, the first line cannot tell you whether the theme got fixed or the validation got deleted. The second says the response is the normal one for a working theme. The third says the schema is still doing its job. Any new user-facing value gets these three before it counts as shipped.

What the theme was for

There is a moment about an hour into a child's birthday party. The wrapping paper is on the floor, the guests have moved outside, and two or three presents are still on the table that nobody has gone back to. At the parties we have been to, almost everything left there had the child's name printed on it: the mug, the T-shirt, the wooden puzzle cut into the letters. The child read the name once, confirmed it was theirs, and left. A name is a check, and checks finish.

That is the hour the theme was written for, and we should be exact about what it is: something we have watched, not something we counted. No sample, no control group, none of the discipline of the section above. It stays an observation, and it costs nothing to run at the next party you go to: wait an hour, then read what is still on the table.

Disclosure, because it decides what counts as a bug here: we build Lumora, which takes one photo of a child and writes and illustrates a story with that child inside it rather than printed on the cover. What we are aiming at is a birthday gift a child is still reading after the guests have gone home. The theme built for that hour was, for one day, the only one the API refused to accept — and the six sample books we spent the day reviewing all rendered beautifully, which is exactly why nobody noticed.

«es» no es un mercado: el bug de i18n que nos costó reescribir una campaña entera

Lumora — Fri, 07 Aug 2026 15:18:24 +0000

Nota: en Lumora construimos libros infantiles personalizados con IA, y escribimos en diez idiomas.
Este artículo cuenta un problema de i18n con el que chocamos de frente y cómo lo resolvimos. Lo contamos
desde dentro, con nuestro nombre, porque el error nos costó reescribir una campaña entera.

Casi todos los equipos tratamos el idioma como si fuera el país. Ponemos es en el selector, sacamos las cadenas a un JSON y damos el problema por cerrado. Funciona hasta el día en que tu producto tiene algo que ver con una fecha.

Y entonces descubres que es no es un mercado, son varios calendarios distintos que comparten vocabulario.

El día en que el regalo no llega el 25

Teníamos una campaña de regalos escrita en español. Correcta gramaticalmente, revisada, sin errores de traducción. Y aun así estaba mal para una parte grande de quien la leía:

En España, el gran momento de regalo infantil no es el 25 de diciembre: son los Reyes Magos, el 6 de enero. Un mensaje que dice "pídelo antes del 24" le está dando a una familia española una fecha límite equivocada por casi dos semanas.
En México conviven las dos cosas: Navidad y Reyes, con la rosca del 6 de enero.
En Argentina, Chile o Uruguay, la Navidad es el 25 de diciembre… en pleno verano. A 30 grados. Con las vacaciones escolares largas empezando, no terminando.

Fíjate en lo incómodo del asunto: los tres casos hablan español. Los tres pasan el mismo test de traducción. Y los tres necesitan un mensaje distinto, una imagen distinta y una fecha límite distinta.

El mismo golpe existe en portugués. En Brasil la Navidad también cae en pleno verano, enero es mes de vacaciones, y el día en que de verdad se reinicia la rutina familiar no es el 1 de enero: es la volta às aulas, en febrero. Si tu calendario de contenidos asume "año nuevo, hábitos nuevos" en enero, en Brasil llegas un mes antes de que a nadie le importe.

Por qué el código de locale no te salva

La respuesta obvia es "usa es-ES y es-AR". Es correcta y casi nunca es suficiente, por dos razones prácticas:

1. La cadena se colapsa. En cuanto el locale viaja por un Accept-Language, un navigator.language, una URL /es o un CDN, casi todo el mundo acaba normalizando a los dos primeros caracteres. Nuestra propia web sirve /es y /pt. El subtag de región existe en teoría y ha desaparecido en la práctica.

2. Estás mezclando dos ejes que no son el mismo. El idioma responde a en qué palabras te hablo. El calendario y el hemisferio responden a en qué momento vives. Un argentino que navega en español desde Madrid y una familia española son el mismo es-ES por cabecera y dos realidades distintas. Y al revés: alguien puede querer el libro en español para un sobrino en Chile.

El bug de fondo es que estábamos derivando una fecha cultural a partir de una etiqueta de idioma. Son dos ejes independientes y los teníamos acoplados.

Lo que cambiamos

Separamos las dos cosas. El idioma decide las palabras. Un concepto aparte, que llamamos "momento de regalo", decide la fecha, la estación y las imágenes:

type Hemisphere = "north" | "south";

interface GiftMoment {
  key: "reyes" | "navidad" | "both";
  giftDate: string;      // la fecha que de verdad importa
  orderBy: string;       // el deadline que mostramos
  hemisphere: Hemisphere;
}

// El idioma NO entra en esta tabla. Solo el territorio.
const GIFT_MOMENTS: Record<string, GiftMoment> = {
  ES: { key: "reyes",   giftDate: "01-06", orderBy: "12-28", hemisphere: "north" },
  MX: { key: "both",    giftDate: "12-25", orderBy: "12-15", hemisphere: "north" },
  AR: { key: "navidad", giftDate: "12-25", orderBy: "12-12", hemisphere: "south" },
  CL: { key: "navidad", giftDate: "12-25", orderBy: "12-12", hemisphere: "south" },
  BR: { key: "navidad", giftDate: "12-25", orderBy: "12-12", hemisphere: "south" },
};

// Dos entradas, no una. Y el idioma nunca se usa para inferir el territorio.
function resolveCampaign(locale: string, country: string) {
  const moment = GIFT_MOMENTS[country] ?? GIFT_MOMENTS.ES;
  return {
    copy: t(locale, `campaign.${moment.key}`),
    season: moment.hemisphere === "south" ? "summer" : "winter",
    orderBy: moment.orderBy,
  };
}

Tres consecuencias que no habíamos anticipado:

La nieve es un bug de contenido. Nuestras ilustraciones navideñas por defecto llevaban nieve y bufandas. Para diciembre en el hemisferio sur eso no es "genérico", es sencillamente otra estación. La estación pasó a ser un parámetro del prompt, no una constante.
El deadline es parte del producto. Si lo que entregas se imprime, la fecha límite real depende de la fecha de regalo local. Un único "pide antes del X" global es incorrecto para la mitad de tu audiencia.
Cuando no sabes el país, no adivines por idioma. Preferimos preguntar, o mostrar un texto neutro respecto a la fecha, antes que asumir que es significa España.

La parte que más nos sorprendió: traducir arrastra la cultura de origen

Relacionado con esto, y quizá lo más útil que hemos aprendido: escribimos cada idioma de forma nativa en lugar de traducir desde el inglés.

No fue una decisión estética. Un cuento escrito en inglés y traducido al español llega con las asunciones del original metidas dentro de la estructura: la cena de Nochebuena en el sitio equivocado, el invierno como telón de fondo, los nombres, el ritmo de las frases, incluso qué se considera una travesura. La traducción arregla las palabras y deja intacto el marco cultural. Es exactamente el mismo error que el de las fechas, una capa más arriba.

Si estás construyendo algo multiidioma, esta es la pregunta que nos habría ahorrado más trabajo: ¿esta cadena depende del idioma, o depende del lugar? Si depende del lugar, sácala del sistema de traducción hoy. En cuanto vive en el i18n.json ya está acoplada al idioma y desacoplarla después es mucho más caro.

Por transparencia: esto salió de trabajar en Lumora, donde hacemos libros ilustrados personalizados a partir de una foto. Subes una foto de tu peque, la IA escribe e ilustra el cuento, y el niño o la niña es el protagonista con el mismo aspecto en todas las páginas. Escribimos en diez idiomas de forma nativa, no traducida, y el primer libro es gratis y sin tarjeta.

Si has peleado con esto en otro idioma, nos interesa mucho saber cómo lo resolviste. El caso del árabe nos dio otro problema completamente distinto —de capa de texto en el PDF— y esa es otra historia.