Commencez par un commutateur de langue à la racine de l'application et liez-le à un fournisseur qui stocke la langue actuelle et charge les messages.. Use a selectbox to present options and connect its change événement pour mettre à jour la locale.
In typescript projets, basically define messages en tant que carte par langue, register them with the i18n provider, et exposer un traducteur par binding on your page templates.
Use converters pour formater les nombres et les dates et pour gérer la plurielisation, afin que les chaînes d'interface utilisateur restent correctes dans toutes les langues. Créez une petite application locale messages cataloguer et le charger au démarrage pour éviter un affichage de texte non traduit.
Lorsque l'utilisateur sélectionne une langue dans le language-switch, l'application met à jour la locale et se recharge messages. Si la locale devient undefined, en cas d'échec, revenir à l'anglais. Si vous wanted l'application pour refléter les modifications immédiatement, déclencher une changed événement et rebind des composants affectés.
Gardez les traductions organisées : stockez les clés dans un seul espace de noms, utilisez une lumière page disposition, et just écrivez des tests qui exercent register and binding flows. Si vous want pour accélérer l'intégration, définissez un dictionnaire partagé pour les expressions courantes et documentez vos langues prises en charge. Mettre à jour messages and converters à mesure que votre application se développe.
Étape 1 : Installer le plugin aurelia-i18n et ajouter un fichier 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.
Créez un wrapper léger qui connecte le plugin à votre cycle de vie Aurelia. Le wrapper gère le chargement des données de localisation et expose une fonction de traduction simple. Attendez-vous à des convertisseurs pour formater les nombres et les dates et intégrez-les à la liaison afin qu'un seul converter handles common formatting while converters peut être étendu pour des besoins spécifiques.
Placez translation.json à côté de votre point d'entrée et référencez-le via le chargeur. Un chemin typique est src/assets/i18n/translation.json, et le fichier doit être inclus dans le paquet de l'application pour garantir qu'il est disponible au démarrage, y compris sur Safari où la mise en cache hors ligne peut affecter le chargement.
Example structure for translation.json: { "messages": { "greeting": "Hello, {name}!" }, "labels": { "save": "Save" } }
Notes de stratégie : utiliser des clés indéfinies pour les chaînes larges et réutilisables et des clés spécifiques pour les fragments d'interface utilisateur. Les clés sélectionnées correspondent aux parties d'interface utilisateur requises, afin que les phrases souhaitées restent lisibles dans le code et que les traducteurs puissent renvoyer des résultats précis. Le projet doit évoluer en ajoutant de nouvelles clés sous messages et labels au fur et à mesure que les fonctionnalités changent, sans casser les traductions existantes.
Si vous utilisez aureliavalidation-i18n, alignez les messages de validation dans translation.json afin que le wrapper puisse fournir un retour d'information convivial. Testez sur différents navigateurs, y compris Safari, pour confirmer que les ressources regroupées se chargent correctement et que les changements de locale se reflètent immédiatement dans l'interface utilisateur. La situation devrait devenir claire.
Étape 2 : Créer des dossiers et des fichiers (src/i18n, locales, app.js, main.js)
Créez les dossiers et les fichiers maintenant et intégrez aurelia-i18n à votre application Aurelia, afin que la localisation se charge au démarrage via un backend qui sert les données de locale. Placez la logique i18n source dans src/i18n, et organisez les traductions dans locales ; respectez les conventions de nommage d'Aurelia pour éviter les collisions.
- Structure du dossier et objectif
- src/i18n : contient la configuration, les convertisseurs et tous les adaptateurs i18n personnalisés.
- locales : stocke des paquets JSON spécifiques à chaque langue, chargés avec un motif de glob de fichiers comme locales/**/*.json.
- app.js: exporter un
configurefonction qui enregistre le plugin i18n, le backend et une locale par défaut (sélectionnée). - main.js : démarrer Aurelia, enregistrer le plugin i18n et démarrer l’application avec la liaison pour définir la locale et les messages de langue.
- app.js configuration
- Fonction exportée:
export function configure(aurelia){ ... } - Fournir un chargeur backend pour récupérer les fichiers de locale à partir du chemin des locales, en utilisant
filesgloblikelocales/**/*.json. - Inscription
aurelia-i18net définir la locale par défaut viasélectionné. - Expose a
formathelper ou convertisseurs si vous avez besoin d'un formatage de date ou de nombre personnalisé.
- Fonction exportée:
- Entrée principale et liaison au moment de l’exécution
- main.js démarre Aurelia et crée la liaison pour un élément sélecteur de langue, par exemple, un
<selectbox>lié àsélectionné. - Use
labelkeys fromlocalespour rendre du texte dynamique :${firstname}à partir des données liées (firstname provient de votre modèle de vue). - Retourne l'instance d'application configurée afin que la navigation et le routage fonctionnent avec du contenu localisé.
- main.js démarre Aurelia et crée la liaison pour un élément sélecteur de langue, par exemple, un
- Messages et liaison au moment de l'exécution
- Dans vos modèles de vue, liez-vous aux clés i18n via une liaison ou une fonction d'assistance, par exemple, ,
t('messages.greeting', { firstname: firstname }). - Fournissez quelques traductions nommées, telles que
orderandsélectionné, pour démontrer le changement de locale sans rechargement complet. - Définir des espaces réservés et la mise en forme dans
messagespour prendre en charge les valeurs dynamiques commeprénomandaureliasnaming.
- Dans vos modèles de vue, liez-vous aux clés i18n via une liaison ou une fonction d'assistance, par exemple, ,
Exemple d'organisation en locales
- locales/en-US.json
- locales/de-DE.json
- locales/ru-RU.json
Astuce : utilisez filesglob pour charger automatiquement toutes les traductions, par exemple, locales/**/*.json. Dans vos messages, conservez les clés à plat ou regroupées sous label and messages, donc une liaison comme binding="i18n.t('messages.welcome', { firstname: firstname })" reste propre et précis.
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 qui pointe vers votre serveur ou des fichiers statiques, et définit une valeur par défaut fallbackLocale.
Configure le backend afin que le chargeur puisse demander des fichiers par espace de noms, tels que /i18n/en/common.json ou /i18n/en/home.json. Si une clé est manquante, elle peut être undefined, afin que vous puissiez afficher la clé d'origine ou un message de repli convivial. Gérez les erreurs avec un bloc try/catch autour de la requête et enregistrez-les dans window.console pour le débogage.
Example: dans un modèle, liez-vous aux traductions avec le service i18n. Utilisez des clés comme prénom 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.
Astuce TypeScript: fournissez un accès typé aux clés en déclarant une petite interface et en encapsulant l'appel t(). Cela devient specific à votre projet et aide avec binding dans les modèles. Si vous compilez avec le mode strict, les vérifications non définies deviennent visibles au moment de la compilation.
Gestion des événementsécouter les modifications de la locale via l'événement du plugin, puis appeler une méthode de rafraîchissement pour recharger les bundles de namespace. Ce changement se propage à travers votre binding mises à jour, afin que les composants reflètent la nouvelle langue sans manipulation manuelle du DOM.
Options du backend: héberger les traductions sur un backend dédié, ou les servir en tant que ressources statiques. Dans une configuration simple, vous appelez un request pour récupérer /locales/{lng}/{ns}.json et stocker les résultats en mémoire pour un accès rapide. Le chargeur would provide une solution de repli lorsque la ressource demandée n'est pas trouvée. Cela deviendrait puissant lorsque vous vous connectez à un véritable backend, et vous pouvez search pour couvrir les cas où les utilisateurs mentionnent des éléments dans l'interface utilisateur.
Conseils de performanceprécharger les espaces de noms courants lors du démarrage de l'application, mettre en cache les résultats et éviter les appels réseau répétés. Utiliser around la startup pour récupérer les bundles essentiels, puis cover others on demand. When you test, verify that the key prénom résout correctement entre les composants, et qu'une clé inconnue affiche la valeur de repli d'écran ou la clé elle-même.
Étape 4 : Structurer le fichier JSON de traduction et les clés
Adoptez un seul fichier de traduction pour la locale anglaise et placez-le dans un dossier locales. Chargez des fragments supplémentaires avec un motif de type glob afin que les mises à jour restent centralisées sans modifications manuelles. Maintenez l'arborescence peu profonde et logique afin de prendre en charge des recherches rapides pendant le rendu de l'interface utilisateur.
Organiser par domaines fonctionnels : en-tête, contenu et actions. Dans chaque domaine, attribuer des étiquettes courtes pour les chaînes d'interface utilisateur. Exemple :
{
"header": { "title": "Welcome", "subtitle": "App Guide" },
"content": { "welcome": "Hello" },
"actions": { "submit": "Submit" }
}
Créez un type TypeScript qui reflète la forme JSON. Ce type clarifie la structure et les éditeurs proposent l'autocomplétion. Une approche compacte maintient alignés à la fois les vérifications au moment de l'exécution et au moment de la compilation.
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.
À l'apparition de nouveaux écrans, étendez l'arborescence existante pour maintenir la cohérence. Utilisez un fichier de mapping central comme source de vérité et conservez un petit ensemble de sections racines.
Chargement des notes : utilisez un chargeur pour récupérer le JSON et appliquer les chaînes par chemin, par exemple header.title ou content.welcome.
Exemple de snippet :
{
"header": { "title": "Welcome", "subtitle": "App Guide" },
"content": { "welcome": "Hello" }
}
Étape 5 : Définir la locale et implémenter une zone de sélection de la locale
Associer un contrôle de basculement de langue à la locale active et déclencher un changement sur le fournisseur i18n lorsque l'utilisateur sélectionne une nouvelle langue.
Configure i18n avec i18next-xhr-backend et un filesglob pour charger les traductions en douceur dans l’ensemble du projet. Cette approche couvre le chargement des fichiers JSON pour chaque locale, maintient les clés organisées et prend en charge les dates et les messages spécifiques à la locale. Utilisez le provider pour persister la langue choisie, afin que les utilisateurs voient le contenu correct lors de requêtes ultérieures.
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>
Dans la configuration du backend, utilisez i18next-xhr-backend avec un loadPath et filesglob pour couvrir tous les fichiers de locale. Exemple : backend: { loadPath: '/locales/{{lng}}/{{ns}}.json', filesGlob: '**/*.json' }. Cette configuration prend en charge des paquets linguistiques spécifiques et évite les clés manquantes lors des requêtes. Pour les messages de validation et les dates, connectez aureliavalidation-i18n à vos formulaires afin que les commentaires s'adaptent à la locale actuelle, et assurez-vous que le fournisseur reste la seule source de vérité pour les données linguistiques.
Étape 6 : Vue, tests unitaires et recherches enregistrées pour filtrer les résultats
Lier tous les libellés d'interface utilisateur à des clés de localisation et exposer un panneau de recherches enregistrées pour filtrer les résultats. Il existe un chemin clair utilisant jspm pour charger aurelia-i18n et les polyfills windowintl, puis étendre le chargeur regroupé pour récupérer les paquets de localisation à partir d'un backend ou de fichiers statiques. Avec cette configuration, l'interface se met à jour naturellement lorsque la localisation change, il y a un retour fluide aux filtres précédents, et la durée de vie de l'interface utilisateur reste cohérente. Utilisez un objet d'options pour partager la langue, la région et les formats de date dans la vue afin que l'expérience soit cohérente.
Pour maintenir la rapidité de l'affichage, implémentez un valueconverter pour les dates et les nombres et connectez-le à la locale actuelle. Exemple : un DateValueConverter formate les dates via windowintl lorsque c'est disponible ; sinon, il recourt à l'ISO. Les sources typescript dans aurelia-framework gèrent la logique du convertisseur, et vous pouvez enregistrer le convertisseur globalement. Les clés de label pilotent toutes les chaînes de caractères, et le panneau de recherches enregistrées utilise également des labels sensibles à la locale. Cette approche serait facile à adapter dans un autre module et serait évolutive avec davantage de locales.
View bindings et convertisseurs de valeurs
Dans aurelia-framework, liez le texte aux clés i18n en utilisant la liaison t ou i18n.bind, et utilisez valueconverter pour formater les dates avec des formats choisis par la locale. Le chargeur peut charger les ressources à partir d'actifs regroupés ou d'un backend, et vous pouvez utiliser jspm pour gérer les dépendances d'exécution. Assurez-vous que les dates et les devises s'affichent de manière cohérente sur Safari en incluant les polyfills nécessaires et en testant avec windowintl. Les fichiers de locale d'exemple (en.json, fr.json) conservent les valeurs d'étiquette dans des chaînes simples afin que les traductions restent maintenables.
Tests unitaires et recherches enregistrées
Écrivez des tests unitaires avec aurelia-testing pour vérifier que la vue affiche des chaînes localisées et que les recherches enregistrées filtrent correctement les résultats. Étendez les tests pour couvrir le DateValueConverter dans différentes locales et validez que les recherches enregistrées persistent dans localStorage et sont restaurées lors du rechargement. Utilisez un backend simulé dans les tests si nécessaire et vérifiez que le loader renvoie des bundles pour chaque locale. Une fois terminé, exécutez les tests dans votre runner préféré ; cela réduira le risque de régressions et vous aidera à étendre la couverture i18n dans les deux sens.
