Comienza con un cambio de idioma en la raíz de la aplicación y vincúlalo a un proveedor que almacene el idioma actual y cargue mensajes. Use a selectbox para presentar opciones y conectar su change evento para actualizar la configuración regional.
In typescript proyectos, básicamente define messages como un mapa por idioma, register them with the i18n provider, y exponer un traductor a través de binding on your page templates.
Use converters para formatear números y fechas y para manejar la pluralización, de modo que las cadenas de la interfaz de usuario se mantengan correctas entre idiomas. Construye una pequeña aplicación local messages catalogar y cargarlo al inicio para evitar el parpadeo de texto no traducido.
Cuando el usuario selecciona un idioma en el language-switch, la aplicación actualiza la configuración regional y se vuelve a cargar messages. Si la configuración regional se convierte en Translation not available or invalid., volver a inglés. Si usted wanted la aplicación para reflejar los cambios inmediatamente, activar una changed evento y volver a enlazar los componentes afectados.
Mantener las traducciones organizadas: almacenar las claves en un único espacio de nombres, usar una luz page diseño, y just escribir pruebas que ejercitan register and binding flows. Si usted want Para acelerar la incorporación, defina un diccionario compartido para frases comunes y documente sus idiomas compatibles. Actualice messages and converters a medida que tu aplicación crece.
Paso 1: Instalar el plugin aurelia-i18n y añadir un archivo translation.json
Install aurelia-i18n plugin and add a translation.json to your project now to enable i18n from the start. Use jspm to align with a bundled workflow or npm for modern builds: jspm install aurelia-i18n --dev; npm i aurelia-i18n --save.
Cree un envoltorio ligero que conecte el plugin a su ciclo de vida de Aurelia. El envoltorio se encarga de cargar los datos de la configuración regional y expone una función de traducción simple. Espere convertidores para formatear números y fechas, y conéctelos al enlace para que un solo converter maneja el formato común mientras converters puede extenderse para necesidades especiales.
Coloque translation.json junto con su punto de entrada y refiéralo a través del cargador. Una ruta típica es src/assets/i18n/translation.json, y el archivo debe incluirse en el paquete de la aplicación para garantizar que esté disponible al inicio, incluso en Safari donde el almacenamiento en caché sin conexión puede afectar la carga.
Example structure for translation.json: { "messages": { "greeting": "Hello, {name}!" }, "labels": { "save": "Save" } }
Notas de estrategia: usar claves indefinidas para cadenas amplias y reutilizables y claves específicas para fragmentos de la interfaz de usuario. Las claves seleccionadas se asignan a las partes de la interfaz de usuario necesarias, para que las frases deseadas permanezcan legibles en el código y los traductores puedan devolver resultados precisos. El proyecto debería evolucionar mediante la adición de nuevas claves dentro de mensajes y etiquetas a medida que cambian las funciones, sin romper las traducciones existentes.
Si utiliza aureliavalidation-i18n, alinee los mensajes de validación en translation.json para que el wrapper pueda ofrecer una retroalimentación fácil de usar. Pruebe en varios navegadores, incluido Safari, para confirmar que los recursos empaquetados se cargan correctamente y que los cambios de ubicación se reflejan inmediatamente en la interfaz de usuario si la situación se aclara.
Paso 2: Crear carpetas y archivos (src/i18n, locales, app.js, main.js)
Cree las carpetas y los archivos ahora y conecte aurelia-i18n a su aplicación Aurelia, para que la localización se cargue al inicio a través de un backend que sirva datos de ubicación. Coloque la lógica i18n de origen en src/i18n, y organice las traducciones en locales; mantenga las convenciones de nombres de Aurelia para evitar colisiones.
- Estructura de carpetas y propósito
- src/i18n: contiene la configuración, los conversores y cualquier adaptador i18n personalizado.
- locales: almacena paquetes JSON por idioma, cargados con un patrón de archivosglob como locales/**/*.json.
- app.js: exportar una
configurefunción que registra el plugin de i18n, el backend y un idioma predeterminado (seleccionado). - main.js: bootstrap Aurelia, registrar el plugin i18n e iniciar la aplicación con enlace para establecer la configuración regional y los mensajes de idioma.
- app.js configuración
- Función exportada:
export function configure(aurelia){ ... } - Proporcione un cargador de backend para obtener archivos de configuración regional desde la ruta de configuración regional, utilizando
filesgloblikelocales/**/*.json. - Register
aurelia-i18ny configurar la configuración regional predeterminada a través deseleccionado. - Expose a
formathelper o convertidores si necesita un formato de fecha o número personalizado.
- Función exportada:
- Entrada principal y enlace en tiempo de ejecución
- main.js inicia Aurelia y crea el enlace para un elemento selector de idioma, p. ej., un
<selectbox>sujeto aseleccionado. - Use
labelclaves delocalespara renderizar texto dinámico:${firstname}desde los datos vinculados (firstname proviene de tu view-model). - Devuelve la instancia de la aplicación configurada para que la navegación y el enrutamiento funcionen con contenido localizado.
- main.js inicia Aurelia y crea el enlace para un elemento selector de idioma, p. ej., un
- Mensajes y enlace en tiempo de ejecución
- En tus plantillas de vista, enlaza a claves de i18n mediante un enlace o auxiliar, p. ej.,
t('messages.greeting', { firstname: firstname }). - Proporcione algunas traducciones con nombre, como
orderandseleccionado, para demostrar el cambio de configuración regional sin una recarga completa. - Define placeholders and formatting in
messagespara soportar valores dinámicos comofirstnameandaureliasnaming.
- En tus plantillas de vista, enlaza a claves de i18n mediante un enlace o auxiliar, p. ej.,
Organización de muestra en locales
- locales/en-US.json
- locales/de-DE.json
- locales/ru-RU.json
Tip: use filesglob para cargar todas las traducciones automáticamente, p. ej., locales/**/*.json. En tus mensajes, mantén las claves planas o agrupadas bajo label and messages, así que un enlace como binding="i18n.t('messages.welcome', { firstname: firstname })" permanece limpio y específico.
Step 3: Use a plugin with TypeScript and Aurelia's loader
Install aurelia-i18nt and register it with Aurelia's loader in your TypeScript bootstrap to enable dynamic translation loading. This setup lets the loader fetch translation bundles on demand, so you don't ship all strings upfront. Use the option backend with a loadPath que apunta a tu servidor o archivos estáticos, y establece un valor predeterminado fallbackLocale.
Configure el backend para que el cargador pueda solicitar archivos por espacio de nombres, como /i18n/en/common.json o /i18n/en/home.json. Si una clave falta, podría ser Translation not available or invalid., así que puedes mostrar la clave original o un valor de retorno amigable. Maneja los errores con un bloque try/catch alrededor de la solicitud y regístralos en window.console para depurar.
Example: en una plantilla, enlazar con las traducciones usando el servicio i18n. Usar claves como firstname to render the user's given name and support a namespace greeting. Example: binding with i18n.t('greeting.firstname') or i18n.t('home:firstname') covers different contexts.
Consejo de TypeScript: proporcione acceso tipeado a las claves declarando una pequeña interfaz y envolviendo la llamada t(). Esto se convierte en specific to your project and helps with binding en las plantillas. Si compila con modo estricto, las comprobaciones indefinidas se hacen visibles en tiempo de compilación.
Manejo de eventos: escuchar cambios de localización a través del evento del plugin, luego llamar a un método de actualización para volver a cargar los paquetes de espacio de nombres. Este cambio fluye a través de tu binding actualizaciones, para que los componentes reflejen el nuevo idioma sin manipulación manual del DOM.
Opciones de backend: alojar las traducciones en un backend dedicado o servirlas como activos estáticos. En una configuración simple, llamas a request para obtener /locales/{lng}/{ns}.json y almacenar los resultados en la memoria para un acceso rápido. El cargador would provide una opción alternativa cuando no se encuentra el recurso solicitado. Esto se volvería poderoso cuando se conecte a un backend real, y usted puede search claves a través de los espacios de nombres cargados para cubrir los casos que los usuarios nombran en la interfaz de usuario.
Consejos de rendimientoprecargar espacios de nombres comunes durante el inicio de la aplicación, almacenar en caché los resultados y evitar llamadas de red repetidas. Usar around la startup para obtener paquetes esenciales, luego cover otros bajo demanda. Cuando pruebes, verifica que la firstname se resuelve correctamente entre componentes, y que una clave desconocida muestre el valor de respaldo o la clave misma.
Paso 4: Estructurar el archivo JSON de Traducción y claves
Adopte un único archivo de traducción para la configuración regional de inglés y colóquelo en una carpeta de 'locales'. Cargue fragmentos adicionales con un patrón similar a glob para que las actualizaciones se mantengan centralizadas sin ediciones manuales. Mantenga la estructura poco profunda y lógica para admitir búsquedas rápidas durante la representación de la interfaz de usuario.
Organizar por áreas de funcionalidad: encabezado, contenido y acciones. Dentro de cada área, asignar etiquetas cortas para las cadenas de IU. Ejemplo:
{
"header": { "title": "Welcome", "subtitle": "App Guide" },
"content": { "welcome": "Hello" },
"actions": { "submit": "Submit" }
}
Cree un tipo de TypeScript que refleje la forma del JSON. Este tipo aclara la estructura y los editores ofrecen autocompletado. Un enfoque conciso mantiene alineadas tanto las comprobaciones en tiempo de ejecución como las de tiempo de compilación.
Handle date-like strings with simple placeholders and a separate formatting utility. Example: "today": "Today is {date}". The runtime applies a date formatter or a dedicated function, keeping strings readable and plain.
A medida que aparecen nuevas pantallas, extiende el árbol existente para mantener la consistencia. Utiliza un archivo de mapeo central como la fuente de la verdad, y mantén un pequeño conjunto de secciones raíz.
Cargando notas: utiliza un cargador para obtener el JSON y aplicar cadenas por ruta como header.title o content.welcome.
Ejemplo de fragmento:
{
"header": { "title": "Welcome", "subtitle": "App Guide" },
"content": { "welcome": "Hello" }
}
Paso 5: Establecer la configuración regional e implementar una caja de selección de configuración regional
Asociar un control de cambio de idioma con la localización activa y desencadenar un cambio en el proveedor de i18n cuando el usuario selecciona un nuevo idioma.
Configurar i18n con i18next-xhr-backend y un filesglob para que las traducciones se carguen sin problemas en todo el proyecto. Este enfoque cubre la carga de archivos JSON para cada idioma local, mantiene las claves organizadas y admite fechas y mensajes específicos de la configuración regional. Utiliza el proveedor para persistir el idioma elegido, para que los usuarios vean el contenido correcto en solicitudes posteriores.
Implementation details
// View-model
import { I18N } from 'aurelia-i18n';
export class App {
static inject = [I18N];
constructor(i18n) {
this.i18n = i18n;
this.locale = localStorage.getItem('locale') || 'en';
}
changeLocale(locale) {
this.locale = locale;
this.i18n.setLocale(locale);
localStorage.setItem('locale', locale);
}
}
<select value.bind="locale" change.delegate="changeLocale(locale)">
<option value="en">English</option>
<option value="ru">Русский</option>
<option value="es">Español</option>
</select>
En la configuración del backend, use i18next-xhr-backend con una ruta de carga y un glob de archivos para cubrir todos los archivos de idioma. Ejemplo: backend: { loadPath: '/locales/{{lng}}/{{ns}}.json', filesGlob: '**/*.json' }. Esta configuración admite paquetes de idioma específicos y evita claves faltantes durante las solicitudes. Para los mensajes de validación y las fechas, integra aureliavalidation-i18n en tus formularios para que la retroalimentación se adapte al entorno regional actual, y asegúrate de que el proveedor siga siendo la única fuente de verdad para los datos del idioma.
Paso 6: Ver, pruebas unitarias y búsquedas guardadas para filtrar resultados
Vincular todas las etiquetas de la interfaz de usuario con claves de localización y exponer un panel de búsquedas guardadas para filtrar los resultados. Existe un camino claro usando jspm para cargar aurelia-i18n y polyfills de windowintl, luego extender el cargador agrupado para obtener paquetes de localización de un backend o archivos estáticos. Con esta configuración, la interfaz se actualiza de forma natural cuando cambia la localización, hay un retorno fluido a los filtros anteriores y la vida de la interfaz de usuario se mantiene consistente. Utilizar un objeto de opciones para compartir el idioma, la región y los formatos de fecha en toda la vista para que la experiencia se sienta cohesiva.
Para mantener la vista rápida, implementa un valorconvertidor para fechas y números y conéctalo a la configuración regional actual. Ejemplo: un DateValueConverter formatea fechas a través de windowintl cuando está disponible; de lo contrario, recurre a ISO. Las fuentes typescript en el aurelia-framework manejan la lógica del convertidor, y puedes registrar el convertidor globalmente. Las claves de etiqueta controlan todas las cadenas, y el panel de búsquedas guardadas también utiliza etiquetas conscientes de la configuración regional. Este enfoque sería fácil de adaptar en otro módulo y escalaría con más configuraciones regionales.
Vínculos de visualización y convertidores de valores
En el marco de aurelia-framework, vincula texto a claves i18n usando el enlace 't' o i18n.bind, y usa valueconverter para formatear fechas con formatos elegidos por la configuración regional. El cargador puede cargar recursos desde activos agrupados o un backend, y puedes usar jspm para administrar las dependencias de tiempo de ejecución. Asegura que las fechas y divisas se muestren de forma consistente en Safari incluyendo polyfills necesarios y probando con windowintl. Los archivos de configuración regional de ejemplo (en.json, fr.json) mantienen los valores de etiqueta en cadenas simples para que las traducciones se mantengan manejables.
Pruebas unitarias y búsquedas guardadas
Escribe pruebas unitarias con aurelia-testing para verificar que la vista renderiza cadenas localizadas y que las búsquedas guardadas filtran los resultados correctamente. Extiende las pruebas para cubrir DateValueConverter en diferentes locales, y valida que las búsquedas guardadas persisten en localStorage y se restauran al recargar. Usa un backend falso en las pruebas si es necesario y verifica que el cargador devuelve paquetes para cada locale. Una vez finalizado, ejecuta las pruebas en tu runner preferido; esto reducirá el riesgo de regresión y te ayudará a ampliar la cobertura i18n allí y de vuelta.
