Skip to main content

Angular i18n με Transloco: Οδηγός ρύθμισης και μετάφρασης

Από την εγκατάσταση έως την παραγωγή: ρυθμίστε το Transloco, διαχειριστείτε πληθυντικούς με σύνταξη ICU, προσθέστε έξυπνες εναλλακτικές τοπικές ρυθμίσεις και αυτοματοποιήστε τις μεταφράσεις με AI.

1

Εγκαταστήστε το Transloco

Το Transloco είναι η δημοφιλέστερη βιβλιοθήκη i18n τρίτου μέρους για το Angular. Παρέχει φόρτωση μεταφράσεων κατά την εκτέλεση, υποστήριξη της μορφής μηνυμάτων ICU, πεδία εφαρμογής με οκνηρή φόρτωση και ένα εύχρηστο API προτύπων με δομικές οδηγίες και pipes.

Γιατί να επιλέξετε το Transloco αντί για το ενσωματωμένο i18n του Angular; Η ενσωματωμένη λύση του Angular απαιτεί ξεχωριστό build για κάθε γλώσσα και δεν υποστηρίζει εναλλαγή γλώσσας κατά την εκτέλεση. Το Transloco φορτώνει τις μεταφράσεις κατά την εκτέλεση, ώστε να διαθέτετε ένα build και να αλλάζετε γλώσσα άμεσα.
Terminal
npm install @jsverse/transloco
2

Ρυθμίστε το Transloco

Καταχωρίστε το Transloco στη διαμόρφωση της εφαρμογής σας. Πρέπει να δηλώσετε τις διαθέσιμες γλώσσες, να ορίσετε μια προεπιλεγμένη γλώσσα και να ρυθμίσετε τον φορτωτή μεταφράσεων. Το Transloco υποστηρίζει τόσο αυτόνομα στοιχεία (Angular 14+) όσο και μοτίβα NgModule.

Αυτόνομα στοιχεία (συνιστάται)

app.config.ts
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import {
  provideTransloco,
  TranslocoHttpLoader,
} from '@jsverse/transloco';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideTransloco({
      config: {
        availableLangs: ['en', 'de', 'ja', 'es', 'fr'],
        defaultLang: 'en',
        fallbackLang: 'en',
        reRenderOnLangChange: true,
        prodMode: true,
      },
      loader: TranslocoHttpLoader,
    }),
  ],
};

Μοτίβο NgModule

app.module.ts
// app.module.ts
import { NgModule } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import {
  TranslocoModule,
  TRANSLOCO_LOADER,
  TranslocoHttpLoader,
  provideTransloco,
} from '@jsverse/transloco';

@NgModule({
  imports: [TranslocoModule],
  providers: [
    provideTransloco({
      config: {
        availableLangs: ['en', 'de', 'ja', 'es', 'fr'],
        defaultLang: 'en',
        fallbackLang: 'en',
        reRenderOnLangChange: true,
        prodMode: true,
      },
      loader: TranslocoHttpLoader,
    }),
  ],
})
export class AppModule {}
Αν οι μεταφράσεις εμφανίζονται ως ανεπεξέργαστα κλειδιά, όπως "nav.home", αντί για "Home", η συνηθέστερη αιτία είναι ότι το TranslocoHttpLoader δεν μπορεί να βρει τα αρχεία JSON. Βεβαιωθείτε ότι τα αρχεία μεταφράσεων βρίσκονται στο src/assets/i18n/ και ότι ο πίνακας assets στο angular.json περιλαμβάνει αυτή τη διαδρομή.

Δημιουργήστε αρχεία μεταφράσεων

Δημιουργήστε ένα αρχείο JSON ανά γλώσσα στο src/assets/i18n/. Χρησιμοποιήστε ένθετα κλειδιά για να οργανώσετε τις συμβολοσειρές ανά λειτουργία. Το Transloco χρησιμοποιεί τη μορφή μηνυμάτων ICU για πληθυντικούς και μεταβλητές.

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

// assets/i18n/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Uber uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {{ name }}!",
  "cart": {
    "itemCount": "{count, plural, one {# Artikel} other {# Artikel}}"
  }
}
3

Χρησιμοποιήστε μεταφράσεις σε πρότυπα και υπηρεσίες

Το Transloco παρέχει τρεις τρόπους μετάφρασης σε πρότυπα: τη δομική οδηγία (*transloco), το pipe (| transloco) και την υπηρεσία (TranslocoService) για κώδικα TypeScript. Η δομική οδηγία συνιστάται στις περισσότερες περιπτώσεις, επειδή δημιουργεί μία μόνο συνδρομή και παρέχει τη συνάρτηση μετάφρασης σε ολόκληρο το μπλοκ του προτύπου.

Μετάφραση προτύπου

component.html
<!-- Using the transloco directive (recommended) -->
<ng-container *transloco="let t">
  <h1>{{ t('greeting', { name: userName }) }}</h1>
  <nav>
    <a routerLink="/">{{ t('nav.home') }}</a>
    <a routerLink="/about">{{ t('nav.about') }}</a>
  </nav>
</ng-container>

<!-- Using the transloco pipe -->
<h1>{{ 'greeting' | transloco:{ name: userName } }}</h1>

<!-- Using the structural directive with read -->
<ng-container *transloco="let t; read: 'nav'">
  <a routerLink="/">{{ t('home') }}</a>
  <a routerLink="/about">{{ t('about') }}</a>
</ng-container>
Χρησιμοποιήστε την παράμετρο read στη δομική οδηγία, για να περιορίσετε τις μεταφράσεις σε ένα ένθετο κλειδί. Έτσι δεν χρειάζεται να επαναλαμβάνετε το πρόθεμα σε κάθε κλήση t() και τα πρότυπα παραμένουν πιο ευανάγνωστα.

Μετάφραση υπηρεσίας (TypeScript)

notification.component.ts
import { Component, inject } from '@angular/core';
import { TranslocoService } from '@jsverse/transloco';

@Component({
  selector: 'app-notification',
  template: '<span>{{ message }}</span>',
})
export class NotificationComponent {
  private translocoService = inject(TranslocoService);
  message = '';

  showSuccess() {
    // Translate in TypeScript
    this.message = this.translocoService.translate('notifications.saved');
  }

  switchLanguage(lang: string) {
    this.translocoService.setActiveLang(lang);
  }
}
Το pipe transloco δημιουργεί νέα συνδρομή για κάθε χρήση. Σε πρότυπα με πολλές μεταφρασμένες συμβολοσειρές, προτιμήστε τη δομική οδηγία *transloco, η οποία δημιουργεί μία συνδρομή για ολόκληρο το μπλοκ.
4

Διαχειριστείτε πληθυντικούς με τη μορφή μηνυμάτων ICU

Το Transloco χρησιμοποιεί τη μορφή μηνυμάτων ICU για πληθυντικούς και εκφράσεις select. Το ICU διαχειρίζεται αυτόματα σύνθετους κανόνες πληθυντικού — Αραβικά (6 μορφές), Ρωσικά (3 μορφές), Ιαπωνικά (1 μορφή) — από μία μόνο συμβολοσειρά μηνύματος. Ορίστε τους κανόνες πληθυντικού στα αρχεία μεταφράσεων και το Transloco θα επιλέγει τη σωστή μορφή κατά την εκτέλεση.

ICU plural syntax
// assets/i18n/en.json
{
  "cart": {
    "itemCount": "{count, plural, one {# item} other {# items}}",
    "emptyMessage": "Your cart is empty"
  },
  "notifications": {
    "unread": "{count, plural, =0 {No new notifications} one {# new notification} other {# new notifications}}"
  }
}

// assets/i18n/ar.json — Arabic has 6 plural forms
{
  "cart": {
    "itemCount": "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصرًا} other {# عنصر}}"
  }
}

// Template usage:
// <span>{{ t('cart.itemCount', { count: cartItems.length }) }}</span>
Μην υλοποιείτε ποτέ δική σας λογική πληθυντικού στα στοιχεία σας. Οι κανόνες πληθυντικού διαφέρουν δραστικά μεταξύ των γλωσσών και καλύπτονται ήδη από την προδιαγραφή ICU. Αφήστε το Transloco και το ICU να αναλάβουν τη διαχείριση — εσείς χρειάζεται μόνο να ορίσετε τις σωστές μορφές πληθυντικού στα αρχεία μεταφράσεων.

Έξυπνες εναλλακτικές τοπικές ρυθμίσεις με το angular-locale-chain

Από προεπιλογή, το Transloco καταφεύγει στην προεπιλεγμένη τοπική ρύθμιση όταν λείπει ένα κλειδί μετάφρασης. Ένας χρήστης pt-BR βλέπει Αγγλικά αντί για τις απολύτως κατάλληλες μεταφράσεις pt-PT. Το angular-locale-chain επιλύει το πρόβλημα, συγχωνεύοντας σε βάθος τις μεταφράσεις από μια διαμορφώσιμη αλυσίδα εναλλακτικών πριν τις παραδώσει στο Transloco. Κάθε κλειδί συμπληρώνεται — χωρίς κενά και χωρίς ελλιπείς μεταφράσεις.

Terminal
npm install angular-locale-chain
app.config.ts (with locale chain)
// app.config.ts — with angular-locale-chain
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import {
  provideTransloco,
  TranslocoHttpLoader,
  TRANSLOCO_LOADER,
  TRANSLOCO_FALLBACK_STRATEGY,
} from '@jsverse/transloco';
import {
  LocaleChainLoader,
  LocaleChainFallbackStrategy,
} from 'angular-locale-chain';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideTransloco({
      config: {
        availableLangs: ['en', 'fr', 'fr-CA', 'pt', 'pt-BR', 'de', 'de-AT'],
        defaultLang: 'en',
        fallbackLang: 'en',
        reRenderOnLangChange: true,
        prodMode: true,
      },
    }),
    {
      provide: TRANSLOCO_LOADER,
      useFactory: () => {
        const inner = new TranslocoHttpLoader();
        return new LocaleChainLoader(inner, {
          defaultLocale: 'en',
        });
      },
    },
    {
      provide: TRANSLOCO_FALLBACK_STRATEGY,
      useFactory: () => new LocaleChainFallbackStrategy(),
    },
  ],
};
Το angular-locale-chain είναι μια βιβλιοθήκη ανοικτού κώδικα που επιλύει το bug #574 του Transloco — την απουσία εναλλακτικής ανά κλειδί όταν ένα αρχείο μετάφρασης είναι μερικώς συμπληρωμένο.

Συνιστώμενη δομή αρχείων

Project Structure
my-angular-app/
├── src/
│   ├── assets/
│   │   └── i18n/
│   │       ├── en.json           # Source language
│   │       ├── de.json           # German
│   │       ├── ja.json           # Japanese
│   │       ├── es.json           # Spanish
│   │       └── fr.json           # French
│   ├── app/
│   │   ├── app.config.ts         # Transloco provider config
│   │   ├── app.component.ts
│   │   └── components/
│   │       └── lang-switcher/
│   │           └── lang-switcher.component.ts
│   └── main.ts
├── angular.json
└── package.json

Αυτοματοποιήστε τις μεταφράσεις

Αφού ολοκληρώσετε τη ρύθμιση του Transloco, μεταφράστε τα αρχεία γλωσσών με AI. Στο IDE σας, ζητήστε από τον βοηθό AI να μεταφράσει το αρχείο JSON προέλευσης ή χρησιμοποιήστε το i18n Agent CLI στο pipeline CI/CD για πλήρως αυτοματοποιημένη τοπική προσαρμογή.

Terminal
# In your IDE, ask your AI assistant:
> Translate src/assets/i18n/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/assets/i18n/en.json --lang de,ja,es
Μεταφράζετε σταδιακά — όταν προσθέτετε νέα κλειδιά στο αρχείο προέλευσης, μεταφράστε μόνο τις διαφορές αντί να δημιουργείτε ξανά όλα τα αρχεία. Έτσι διατηρούνται οι μεταφράσεις που έχουν ελεγχθεί από άνθρωπο και αποφεύγονται οι περιττές αλλαγές.

Αυτοματοποιήστε τον έλεγχο ποιότητας των μεταφράσεων

Εντοπίστε κλειδιά που λείπουν και κατεστραμμένα placeholders πριν φτάσουν στην παραγωγή με το i18n-validate. Δοκιμάστε το UI σας με ψευδομεταφράσεις μέσω του i18n-pseudo πριν είναι διαθέσιμες οι πραγματικές μεταφράσεις.

Συνηθισμένες παγίδες

Οι μεταφράσεις εμφανίζουν ανεπεξέργαστα κλειδιά

Το TranslocoHttpLoader δεν μπορεί να βρει τα αρχεία JSON. Ελέγξτε ότι τα αρχεία βρίσκονται στο src/assets/i18n/, ότι ο πίνακας assets στο angular.json περιλαμβάνει αυτή τη διαδρομή και ότι τα ονόματα των αρχείων αντιστοιχούν ακριβώς στη διαμόρφωση availableLangs, με διάκριση πεζών και κεφαλαίων.

Τα κλειδιά περιορισμένου πεδίου δεν επιλύονται

Όταν χρησιμοποιείτε πεδία εφαρμογής Transloco, τα αρχεία μεταφράσεων πρέπει να βρίσκονται στο assets/i18n/[scope]/[lang].json και όχι στον ριζικό φάκελο i18n. Βεβαιωθείτε επίσης ότι το πεδίο εφαρμογής έχει καταχωριστεί στον πίνακα providers του στοιχείου μέσω του TRANSLOCO_SCOPE.

Προειδοποιήσεις στην κονσόλα στο περιβάλλον παραγωγής

Ορίστε prodMode: true στη διαμόρφωση του Transloco για τα build παραγωγής. Χωρίς αυτή τη ρύθμιση, το Transloco καταγράφει στην κονσόλα προειδοποιήσεις για κλειδιά που λείπουν. Απενεργοποιεί επίσης ελέγχους ανάπτυξης που επιβαρύνουν την απόδοση.

Στιγμιαία εμφάνιση ανεπεξέργαστων μεταφράσεων κατά την πλοήγηση

Οι διαδρομές με οκνηρή φόρτωση ανακτούν τις μεταφράσεις αφού αποδοθεί το στοιχείο, προκαλώντας μια σύντομη εμφάνιση αμετάφραστων κλειδιών. Χρησιμοποιήστε το ενσωματωμένο TRANSLOCO_LOADING_TEMPLATE του Transloco για να εμφανίσετε μια κατάσταση φόρτωσης ή προφορτώστε τις μεταφράσεις σε έναν route guard.

Οι χρήστες περιφερειακών παραλλαγών βλέπουν Αγγλικά αντί για τη γονική τοπική ρύθμιση

Η ενσωματωμένη εναλλακτική του Transloco ενεργοποιείται μόνο όταν λείπει ολόκληρο το αρχείο μιας τοπικής ρύθμισης και όχι για μεμονωμένα κλειδιά. Χρησιμοποιήστε το angular-locale-chain για να συγχωνεύσετε σε βάθος μεταφράσεις από συναφείς τοπικές ρυθμίσεις (π.χ. το pt-BR καταφεύγει στο pt-PT, έπειτα στο pt και τέλος στα Αγγλικά).

Δοκιμάστε τώρα το i18n Agent

Αφήστε εδώ το αρχείο μετάφρασής σας

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

ή κάντε κλικ για να επιλέξετε αρχείο

Γλώσσες-στόχοι

Δεν απαιτείται εγγραφήΆμεση εκτίμηση

Εναλλακτική τοπική ρύθμιση με το angular-locale-chain

Όταν λείπει ένα κλειδί μετάφρασης από μια περιφερειακή τοπική ρύθμιση όπως η pt-BR, το TranslocoLoader του Angular μεταβαίνει απευθείας στην προεπιλεγμένη τοπική ρύθμιση αντί να ελέγξει πρώτα τη γονική pt.

Terminal
npm install angular-locale-chain
Configuration
import { LocaleChainLoader } from 'angular-locale-chain';

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

Δείτε τον Οδηγό εναλλακτικών τοπικών ρυθμίσεων για τον πλήρη κατάλογο των υποστηριζόμενων framework και των 75 ενσωματωμένων αλυσίδων. Learn more →

Συχνές ερωτήσεις για το Angular i18n