Skip to main content

i18n en SvelteKit: guía de configuración de internacionalización

Del inicio a una aplicación multilingüe: configure svelte-i18n en SvelteKit con formato de mensajes ICU, enrutamiento regional y cadenas de respaldo inteligentes.

1

Instalar svelte-i18n

svelte-i18n es la biblioteca estándar de internacionalización para Svelte y SvelteKit. Incluye stores reactivos, compatibilidad con ICU MessageFormat y carga diferida de configuraciones regionales de serie.

svelte-i18n utiliza ICU MessageFormat para plurales y variables, el mismo estándar que FormatJS/react-intl. Si viene de React, la sintaxis de los mensajes le resultará familiar.
Terminal
npm install svelte-i18n
2

Configurar svelte-i18n

Cree un archivo de configuración de i18n que registre sus configuraciones regionales mediante funciones de importación diferida. svelte-i18n solo obtendrá los mensajes de una configuración cuando se active.

src/lib/i18n.ts
// src/lib/i18n.ts
import { register, init, getLocaleFromNavigator } from 'svelte-i18n';

// Register locale loaders (lazy-loaded)
register('en', () => import('../locales/en.json'));
register('de', () => import('../locales/de.json'));
register('ja', () => import('../locales/ja.json'));
register('es', () => import('../locales/es.json'));

init({
  fallbackLocale: 'en',
  initialLocale: getLocaleFromNavigator(),  // Auto-detect browser language
});
Debe importar el archivo de configuración de i18n en +layout.svelte antes de renderizar cualquier componente. Si aparecen claves sin procesar como 'nav.home', no se importó lo bastante pronto.

Integración con el diseño de SvelteKit

Importe su configuración de i18n en el diseño raíz y proteja el renderizado con el store $isLoading. Así evita que aparezcan brevemente claves sin traducir mientras los datos regionales se cargan de forma asíncrona.

src/routes/+layout.svelte
<!-- src/routes/+layout.svelte -->
<script>
  // Import i18n config — must run before any component renders
  import '../lib/i18n';
  import { isLoading } from 'svelte-i18n';
</script>

{#if $isLoading}
  <p>Loading translations...</p>
{:else}
  <slot />
{/if}

Enrutamiento regional en SvelteKit

Para URL favorables al SEO como /en/about y /de/about, utilice un parámetro de ruta [lang]. Defina la configuración regional de svelte-i18n en la función load del diseño a partir del parámetro de URL.

SvelteKit locale routing
// src/routes/[lang]/+layout.ts
import { locale } from 'svelte-i18n';

export function load({ params }) {
  // Set the active locale from the URL parameter
  locale.set(params.lang);
  return {};
}

// src/routes/[lang]/+layout.svelte
<script>
  import '../../lib/i18n';
  import { isLoading } from 'svelte-i18n';
</script>

{#if $isLoading}
  <p>Loading...</p>
{:else}
  <slot />
{/if}

Formato del archivo de traducción

Cree un archivo JSON por configuración regional. svelte-i18n admite claves anidadas y sintaxis ICU MessageFormat para plurales, variables y expresiones select.

Translation files
// src/locales/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {name}!",
  "cart": {
    "itemCount": "{count, plural, one {# item} other {# items}}"
  }
}

// src/locales/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Uber uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {name}!",
  "cart": {
    "itemCount": "{count, plural, one {# Artikel} other {# Artikel}}"
  }
}
Nombre las claves por lo que describen, no por el lugar donde aparecen: 'cart.itemCount' es mejor que 'homepageCartLabel'. Las claves deben sobrevivir a los rediseños de la interfaz.
3

Utilizar traducciones en los componentes

Importe el store $_ —o $format— desde svelte-i18n y utilícelo en sus plantillas Svelte. El store es reactivo: cuando cambia la configuración regional, todas las cadenas se actualizan automáticamente.

Component.svelte
<script>
  import { _ } from 'svelte-i18n';
</script>

<h1>{$_('greeting', { values: { name: 'World' } })}</h1>

<nav>
  <a href="/">{$_('nav.home')}</a>
  <a href="/about">{$_('nav.about')}</a>
</nav>
Formatting helpers
<script>
  import { _, date, number, time } from 'svelte-i18n';
</script>

<!-- Simple string -->
<p>{$_('greeting', { values: { name: userName } })}</p>

<!-- ICU plurals — handled automatically -->
<p>{$_('cart.itemCount', { values: { count: 3 } })}</p>

<!-- Date formatting -->
<p>{$date(new Date(), { format: 'long' })}</p>

<!-- Number formatting -->
<p>{$number(1999.99, { style: 'currency', currency: 'USD' })}</p>
$_ es un store de Svelte: debe utilizar el prefijo $ en las plantillas. Escribir _('key') sin el signo de dólar devuelve el objeto store, no la cadena traducida.

Cambio de idioma

Cree un selector de idioma vinculado al store $locale. Cuando cambie el valor, svelte-i18n cargará los mensajes de la nueva configuración regional y actualizará de forma reactiva todas las cadenas traducidas.

LanguageSwitcher.svelte
<script>
  import { locale, locales } from 'svelte-i18n';

  const LANGUAGE_NAMES = {
    en: 'English',
    de: 'Deutsch',
    ja: '日本語',
    es: 'Espanol',
  };
</script>

<select bind:value={$locale}>
  {#each $locales as loc}
    <option value={loc}>{LANGUAGE_NAMES[loc] ?? loc}</option>
  {/each}
</select>
4

Gestionar plurales con ICU MessageFormat

svelte-i18n utiliza ICU MessageFormat para pluralizar, el estándar internacional que gestiona todas las categorías CLDR. El árabe tiene 6 formas, el ruso 4 y el japonés 1. Defina las que necesiten sus idiomas de destino y svelte-i18n seleccionará automáticamente la correcta.

ICU plural forms by language
// svelte-i18n uses ICU MessageFormat for plurals
// English:
{
  "items": "{count, plural, one {# item} other {# items}}"
}

// Arabic (6 forms):
{
  "items": "{count, plural, zero {no items} one {item} two {two items} few {# items} many {# items} other {# items}}"
}

// Japanese (1 form):
{
  "items": "{count, plural, other {#個のアイテム}}"
}
Nunca codifique directamente la lógica de singular y plural en los componentes. Idiomas como el francés consideran singular el 0. El árabe, el ruso y el polaco tienen formas que no existen en inglés. Deje que la sintaxis de plural de ICU se encargue.

Respaldos regionales inteligentes con svelte-i18n-locale-chain

svelte-i18n pasa directamente a fallbackLocale cuando falta una clave, sin respaldo intermedio. Un usuario pt-BR ve inglés en vez de traducciones pt-PT perfectamente válidas. svelte-i18n-locale-chain lo corrige con cadenas inteligentes que combinan en profundidad mensajes de variantes regionales.

Terminal
npm install svelte-i18n-locale-chain svelte-i18n
src/lib/i18n.ts
// src/lib/i18n.ts
import { initLocaleChain, setLocale } from 'svelte-i18n-locale-chain';

// Replace svelte-i18n's init + register with initLocaleChain
await initLocaleChain({
  loadMessages: (locale) =>
    import(`../locales/${locale}.json`).then(m => m.default),
  defaultLocale: 'en',
  initialLocale: 'pt-BR',
});

// Later, to change locale:
await setLocale('fr-CA');
// fr-CA user sees: fr-CA messages -> fr messages -> en messages
// No missing keys — deep-merged automatically
svelte-i18n-locale-chain gestiona internamente toda la carga de mensajes. No utilice a la vez la función register() de svelte-i18n: initLocaleChain se encarga del registro, la carga y la combinación en profundidad.

Automatizar traducciones

Cuando termine de configurar i18n, traduzca sus archivos de configuración regional con IA. Pida a su asistente de IA desde el IDE que traduzca el archivo de origen o utilice la CLI de i18n Agent en su proceso de CI/CD.

Terminal
# In your IDE, ask your AI assistant:
> Translate src/locales/en.json to German, Japanese, and Spanish

✓ de.json created (1.2s)
✓ ja.json created (1.5s)
✓ es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate src/locales/en.json --lang de,ja,es
Traduzca de forma incremental: cuando añada claves nuevas al archivo de origen, traduzca solo las diferencias en vez de volver a generar todos los archivos. Así conserva las traducciones que ya haya revisado una persona.

Automatizar la calidad de la traducción

Detecte las claves ausentes y los marcadores rotos antes de publicar con i18n-validate. Pruebe la interfaz con pseudotraducciones mediante i18n-pseudo antes de recibir las reales.

Errores habituales

Filtración de configuraciones regionales en SSR de SvelteKit

Los stores de svelte-i18n son singletons. En SSR de SvelteKit, las solicitudes simultáneas comparten el mismo store y la configuración regional de un usuario puede filtrarse en la respuesta de otro. Solución: llame a locale.set() en el hook handle o en la función load del diseño para proporcionar el contexto correcto a cada solicitud.

Utilizar register() con svelte-i18n-locale-chain

No utilice register() de svelte-i18n si emplea svelte-i18n-locale-chain. initLocaleChain gestiona internamente toda la carga. Mezclar ambos provoca cargas duplicadas o en conflicto.

Los errores de sintaxis ICU fallan silenciosamente

Una llave sin pareja o una categoría de plural ausente en cadenas ICU MessageFormat provoca fallos silenciosos: se muestra el mensaje sin procesar en vez del resultado formateado. Valide la sintaxis ICU en su proceso de CI.

Aparición momentánea de contenido sin traducir

Si renderiza componentes antes de terminar de cargar las traducciones, los usuarios ven claves sin procesar. Proteja el diseño con {#if $isLoading}...{:else}...{/if} para mostrar un estado de carga hasta que los mensajes estén listos.

Estructura de archivos recomendada

Project Structure
my-sveltekit-app/
├── src/
│   ├── lib/
│   │   └── i18n.ts              # i18n configuration
│   ├── locales/
│   │   ├── en.json              # Source language
│   │   ├── de.json              # German
│   │   ├── ja.json              # Japanese
│   │   └── es.json              # Spanish
│   └── routes/
│       ├── +layout.svelte       # Import i18n, guard isLoading
│       ├── +page.svelte
│       └── [lang]/              # Optional: locale-based routing
│           ├── +layout.ts       # Set locale from URL param
│           ├── +layout.svelte
│           └── +page.svelte
├── svelte.config.js
└── package.json

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

JSON, YAML, PO, XML, CSV, Markdown, Properties

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Respaldo de configuraciones regionales con svelte-i18n-locale-chain

Cuando falta una clave en una configuración regional como pt-BR, svelte-i18n pasa directamente a la predeterminada en vez de comprobar primero la principal pt.

Terminal
npm install svelte-i18n-locale-chain
Configuration
import { initLocaleChain } from 'svelte-i18n-locale-chain';

initLocaleChain({
  fallbacks: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  },
  defaultLocale: 'en',
});

Consulte nuestra guía de respaldo de configuraciones regionales para ver todos los frameworks admitidos y las 75 cadenas integradas. Learn more →

Preguntas frecuentes