Übersetzen Sie Ihr AdonisJS-Backend-Website mit Intlayer | Internationalisierung (i18n)

adonis-intlayer ist ein leistungsstarkes Internationalisierungs-Paket (i18n) für AdonisJS-Anwendungen, das entwickelt wurde, um Ihre Backend-Dienste weltweit zugänglich zu machen, indem es lokalisierte Antworten basierend auf den Präferenzen des Clients liefert.

Praktische Anwendungsfälle

• Anzeigen von Backend-Fehlern in der Sprache des Benutzers: Wenn ein Fehler auftritt, verbessert das Anzeigen von Nachrichten in der Muttersprache des Benutzers das Verständnis und reduziert Frustration. Dies ist besonders nützlich für dynamische Fehlermeldungen, die in Front-End-Komponenten wie Toasts oder Modalen angezeigt werden könnten.

• Abrufen mehrsprachiger Inhalte: Für Anwendungen, die Inhalte aus einer Datenbank beziehen, stellt die Internationalisierung sicher, dass Sie diese Inhalte in mehreren Sprachen bereitstellen können. Dies ist entscheidend für Plattformen wie E-Commerce-Websites oder Content-Management-Systeme, die Produktbeschreibungen, Artikel und andere Inhalte in der vom Benutzer bevorzugten Sprache anzeigen müssen.

• Senden mehrsprachiger E-Mails: Ob Transaktions-E-Mails, Marketingkampagnen oder Benachrichtigungen – das Senden von E-Mails in der Sprache des Empfängers kann das Engagement und die Effektivität erheblich steigern.

• Mehrsprachige Push-Benachrichtigungen: Für mobile Anwendungen kann das Senden von Push-Benachrichtigungen in der bevorzugten Sprache eines Benutzers die Interaktion und Kundenbindung verbessern. Diese persönliche Note kann dazu führen, dass Benachrichtigungen relevanter und handlungsorientierter wirken.

• Andere Kommunikationen: Jede Form der Kommunikation vom Backend, wie SMS-Nachrichten, Systemwarnungen oder Aktualisierungen der Benutzeroberfläche, profitiert davon, in der Sprache des Benutzers zu sein, was Klarheit gewährleistet und das allgemeine Benutzererlebnis verbessert.

Durch die Internationalisierung des Backends respektiert Ihre Anwendung nicht nur kulturelle Unterschiede, sondern passt sich auch besser an globale Marktanforderungen an, was ein wichtiger Schritt zur weltweiten Skalierung Ihrer Dienste ist.

Erste Schritte

See Application Template on GitHub.

Installation

Um adonis-intlayer zu verwenden, installieren Sie das Paket mit npm:

npm install intlayer adonis-intlayernpx intlayer init

Einrichtung

Konfigurieren Sie die Internationalisierungseinstellungen, indem Sie eine intlayer.config.ts in Ihrem Projektstammverzeichnis erstellen:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.RUSSIAN,
      Locales.JAPANESE,
      Locales.FRENCH,
      Locales.KOREAN,
      Locales.CHINESE,
      Locales.SPANISH,
      Locales.GERMAN,
      Locales.ARABIC,
      Locales.ITALIAN,
      Locales.ENGLISH_UNITED_KINGDOM,
      Locales.PORTUGUESE,
      Locales.HINDI,
      Locales.TURKISH,
      Locales.POLISH,
      Locales.INDONESIAN,
      Locales.VIETNAMESE,
      Locales.UKRAINIAN,
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Deklarieren Sie Ihre Inhalte

Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern:

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      de: "Beispiel für zurückgegebenen Inhalt auf Deutsch",
      "es-ES": "Ejemplo de contenido devuelto en español (España)",
      "es-MX": "Ejemplo de contenido devuelto en español (México)",
    }),
  },
} satisfies Dictionary;

export default indexContent;

Ihre Inhaltsdeklarationen können an beliebiger Stelle in Ihrer Anwendung definiert werden, sofern sie im Verzeichnis contentDir enthalten sind (standardmäßig ./src oder ./app) und mit der Dateierweiterung für Inhaltsdeklarationen übereinstimmen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Weitere Details finden Sie in der Dokumentation zur Inhaltsdeklaration.

AdonisJS-Anwendungseinrichtung

Richten Sie Ihre AdonisJS-Anwendung für die Verwendung von adonis-intlayer ein.

Registrieren Sie die Middleware

Zuerst müssen Sie die intlayer-Middleware in Ihrer Anwendung registrieren.

router.use([() => import("adonis-intlayer/middleware")]);

Definieren Sie Ihre Routen

import router from "@adonisjs/core/services/router";import { t, getIntlayer, getDictionary } from "adonis-intlayer";import indexContent from "../app/index.content";router.get("/t_example", async () => {  return t({    en: "Example of returned content in English",    fr: "Exemple de contenu renvoyé en français",    de: "Beispiel für zurückgegebenen Inhalt auf Deutsch",    "es-ES": "Ejemplo de contenido devuelto en español (España)",    "es-MX": "Ejemplo de contenido devuelto en español (México)",  });});router.get("/getIntlayer_example", async () => {  return getIntlayer("index").exampleOfContent;});router.get("/getDictionary_example", async () => {  return getDictionary(indexContent).exampleOfContent;});

Funktionen

adonis-intlayer exportiert mehrere Funktionen zur Handhabung der Internationalisierung in Ihrer Anwendung:

• t(content, locale?): Grundlegende Übersetzungsfunktion.
• getIntlayer(key, locale?): Ruft Inhalte per Schlüssel aus Ihren Wörterbüchern ab.
• getDictionary(dictionary, locale?): Ruft Inhalte aus einem spezifischen Wörterbuchobjekt ab.
• getLocale(): Ruft die aktuelle Locale aus dem Anfragekontext ab.

Verwendung in Controllern

import type { HttpContext } from "@adonisjs/core/http";import { t } from "adonis-intlayer";export default class ExampleController {  async index({ response }: HttpContext) {    return response.send(      t({        en: "Hello from controller",        de: "Hallo vom Controller",      })    );  }}

Kompatibilität

adonis-intlayer ist vollständig kompatibel mit:

• react-intlayer für React-Anwendungen
• next-intlayer für Next.js-Anwendungen
• vite-intlayer für Vite-Anwendungen

Es funktioniert auch nahtlos mit jeder Internationalisierungslösung über verschiedene Umgebungen hinweg, einschließlich Browsern und API-Anfragen. Sie können die Middleware anpassen, um die Locale über Header oder Cookies zu erkennen:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Andere Konfigurationsoptionen  middleware: {    headerName: "my-locale-header",    cookieName: "my-locale-cookie",  },};export default config;

Standardmäßig interpretiert adonis-intlayer den Accept-Language-Header, um die bevorzugte Sprache des Clients zu bestimmen.

Weitere Informationen zur Konfiguration und zu fortgeschrittenen Themen finden Sie in unserer Dokumentation.

TypeScript konfigurieren

adonis-intlayer nutzt die robusten Fähigkeiten von TypeScript, um den Internationalisierungsprozess zu verbessern. Die statische Typisierung von TypeScript stellt sicher, dass jeder Übersetzungsschlüssel berücksichtigt wird, was das Risiko fehlender Übersetzungen verringert und die Wartbarkeit verbessert.

Stellen Sie sicher, dass die automatisch generierten Typen (standardmäßig unter ./types/intlayer.d.ts) in Ihrer tsconfig.json-Datei enthalten sind.

{  // ... Ihre bestehenden TypeScript-Konfigurationen  "include": [    // ... Ihre bestehenden TypeScript-Konfigurationen    ".intlayer/**/*.ts", // Schließen Sie die automatisch generierten Typen ein  ],}

VS Code-Erweiterung

Um Ihr Entwicklungserlebnis mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code-Erweiterung installieren.

Vom VS Code Marketplace installieren

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen von übersetzten Inhalten.
• Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

Weitere Details zur Verwendung der Erweiterung finden Sie in der Dokumentation zur Intlayer VS Code-Erweiterung.

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dies ermöglicht es Ihnen, zu vermeiden, dass sie in Ihr Git-Repository eingecheckt werden.

Fügen Sie dazu die folgenden Anweisungen zu Ihrer .gitignore-Datei hinzu:

# Ignorieren Sie die von Intlayer generierten Dateien.intlayer