Übersetzen von Zeichenketten

Überblick

Diese Anleitung führt Sie durch die Internationalisierung von Strings in Ihrer Next.js-App mit dem useGT() Hook & der getGT() Funktion.

Wir werden folgende Punkte behandeln:

Wann der useGT() Hook verwendet wird

Wie der useGT() Hook verwendet wird

Verwendung von Variablen

Beispiele

Häufige Fallstricke

In dieser Anleitung beziehen wir uns, wenn wir vom useGT() Hook sprechen, auch auf die getGT() Funktion.

Der einzige Unterschied zwischen beiden ist, wann sie verwendet werden.

Die getGT() Funktion ist eine asynchrone Funktion, die eine versprochene Funktion zurückgibt, während der useGT() Hook die Funktion direkt zurückgibt.

Verwenden Sie die getGT() Funktion in synchronen Komponenten und den useGT() Hook in asynchronen Komponenten.

src/app/page.tsx

import { useGT } from 'gt-next';
export function MyComponent() {
  const translate = useGT();
  const translatedString = translate('Hello, world!');
  return <div>{translatedString}</div>;
}

src/app/page.tsx

import { getGT } from 'gt-next/server';
export async function MyComponent() {
  const translate = await getGT();
  const translatedString = translate('Hello, world!');
  return <div>{translatedString}</div>;
}

Wann sollte der `useGT()`-Hook verwendet werden

Der useGT()-Hook ist ein React-Hook, der verwendet werden kann, um Zeichenketten zu übersetzen.

In den meisten Fällen kannst du die <T>-Komponente verwenden. Wenn jedoch JSX nicht geeignet ist, kann der useGT()-Hook eingesetzt werden.

Einige Fälle, in denen der useGT()-Hook besser geeignet sein könnte, sind:

Bei Eigenschaften, die ausschließlich Zeichenketten erwarten, wie zum Beispiel placeholder- oder title-Attribute.
Wenn die Zeichenkette Teil eines größeren Objekts ist, zum Beispiel:

const user = {
  title: 'Mr.',
  name: 'John',
  description: 'John is a software engineer at General Translation',
}

Hier sollte nur die Eigenschaft description übersetzt werden.

Wann immer möglich, solltest du die <T>-Komponente verwenden. Die <T>-Komponente ermöglicht es dir, JSX-Inhalte zu übersetzen, und ist die empfohlene Methode, um Zeichenketten zu übersetzen.

Wie man den `useGT()` Hook verwendet

Der useGT() Hook muss innerhalb des <GTProvider> aufgerufen werden.

Um einen String zu übersetzen, übergeben Sie den String einfach direkt an die Funktion, die vom Hook zurückgegeben wird.

import { useGT } from 'gt-next';
export function MyComponent() {
  const translate = useGT();
  return <div>{translate('Hello, world!')}</div>;
}

Im Gegensatz zu herkömmlichen i18n-Bibliotheken erfordert der useGT() Hook nicht, dass Sie einen key an die Funktion übergeben. Stattdessen wird der String direkt an die Funktion übergeben.

Das bedeutet, dass Sie keine Wörterbücher benötigen!

Wie man die `getGT()` Funktion verwendet

Andererseits kann die getGT() Funktion, da sie eine asynchrone Funktion ist, in async Komponenten verwendet werden und muss nicht innerhalb des <GTProvider> aufgerufen werden.

Der Kontext für getGT() wird durch die withGTConfig Funktion in Ihrer next.config.ts Datei bereitgestellt.

import { getGT } from 'gt-next/server';
export async function MyComponent() {
  const translate = await getGT();
  return <div>{translate('Hello, world!')}</div>;
}

Verwendung von Variablen

Oft müssen Sie Strings übersetzen, die Variablen enthalten.

Zum Beispiel müssen Sie möglicherweise einen String übersetzen, der numerische Werte enthält.

Um Variablen hinzuzufügen, fügen Sie einfach die Variable als Platzhalter mit {variable} zum String hinzu und übergeben Sie ein Objekt als zweites Argument an die Funktion, die vom Hook zurückgegeben wird.

const price = 100;
const translate = useGT();
translate('There are {count} items in the cart', { count: 10 });

Der {count} Platzhalter wird durch den Wert der count Variable ersetzt.

Dies ermöglicht es Ihnen, dynamische Werte in Ihren Übersetzungen anzuzeigen.

Für weitere Informationen zur API siehe die API-Referenz.

gt-next unterstützt das ICU-Nachrichtenformat, das es Ihnen auch ermöglicht, Ihre Variablen zu formatieren.

const price = 100;
const translate = useGT();
translate('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });

Das ICU-Nachrichtenformat ist eine mächtige Möglichkeit, Ihre Variablen zu formatieren. Für weitere Informationen siehe die ICU-Nachrichtenformat-Dokumentation.

Beispiele

Übersetzen eines Strings in einer Komponente

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  return (
    <div>
      <h1>{t('Hello, world!')}</h1>
    </div>
  )
}

export default function MyComponent() {
  return (
    <div>
      <h1>Hello, world!</h1>
    </div>
  )
}

Übersetzen eines Strings mit Variablen

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const count = 10;
  return (
    <div>
      <h1>{t('There are {count} items in the cart', { count })}</h1>
    </div>
  )
}

export default function MyComponent() {
  const count = 10;
  return (
    <div>
      <h1>There are {count} items in the cart</h1>
    </div>
  )
}

Übersetzen von Teilen eines Objekts

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const users = [
    {
      name: 'John',
      description: t('John is a software engineer at General Translation'),
    },
    {
      name: 'Jane',
      description: t('Jane is a software engineer at Google'),
    },
  ]
  return (
    <div>
      {users.map((user) => (
        <div key={user.name}>
          <h1>{user.name}</h1>
          <p>{user.description}</p>
        </div>
      ))}
    </div>
  )
}

export default function MyComponent() {
  const users = [
    {
      name: 'John',
      description: 'John is a software engineer at General Translation',
    },
    {
      name: 'Jane',
      description: 'Jane is a software engineer at Google',
    },
  ]
  return (
    <div>
      {users.map((user) => (
        <div key={user.name}>
          <h1>{user.name}</h1>
          <p>{user.description}</p>
        </div>
      ))}
    </div>
  )
}

Übersetzen gemeinsamer Konstanten

src/llms.ts

// Custom function to get LLM data with translations
export function getLLMData(t: (content: string) => string) {
  return [
    {
      name: 'GPT-4.1',
      id: 'gpt-4.1',
      description: t('GPT-4.1 is a large language model developed by OpenAI'),
    },
    {
      name: 'Claude 3.7 Sonnet',
      id: 'claude-3-7-sonnet',
      description: t('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
    },
  ]
}

import { getLLMData } from './llms';
import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const llms = getLLMData(t);
  return (
    <div>
      {llms.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{llm.description}</p>
        </div>
      ))}
    </div>
  )
}

src/llms.ts

export const llms = [
  {
    name: 'GPT-4.1',
    id: 'gpt-4.1',
    description: 'GPT-4.1 is a large language model developed by OpenAI',
  },
  {
    name: 'Claude 3.7 Sonnet',
    id: 'claude-3-7-sonnet',
    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
  },
]

import { llms } from './llms';

export default function MyComponent() {
  return (
    <div>
      {llms.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{llm.description}</p>
        </div>
      ))}
    </div>
  )
}

In diesem letzten Beispiel haben wir das llms Array in eine Funktion umgewandelt, die die Daten mit Übersetzungen zurückgibt. Wir haben die t Funktion an die Funktion übergeben, die die Daten zurückgibt.

Alternativ könnten Sie das llms Array auch in einen benutzerdefinierten Hook umwandeln. Dies wird jedoch nicht empfohlen, da Sie sehr vorsichtig sein müssen, wie Sie den useGT() Hook verwenden, um nicht gegen die Regeln von React zu verstoßen.

Häufige Fallstricke

Übersetzung von dynamischen Inhalten

Alle Zeichenketten müssen zur Build-Zeit bekannt sein.

Das bedeutet, dass Sie keine dynamischen Inhalte übersetzen können, die zur Laufzeit generiert oder abgerufen werden.

Dies schließt Variablen ein, selbst wenn sie Zeichenketten sind.

export default function MyComponent() {
  const [dynamicContent, setDynamicContent] = useState('Hello, world!');
  const t = useGT();
  return (
    <div>
      <h1>{t(dynamicContent)}</h1> {/* This will not work */}
    </div>
  )
}

Das CLI-Tool warnt Sie, wenn Sie versuchen, dynamische Inhalte mit dem useGT()-Hook zu übersetzen.

Nächste Schritte

Erfahren Sie, wie Sie JSX-Inhalte bei Bedarf übersetzen.
Erfahren Sie mehr über die <T> Komponente.
Sehen Sie sich die API-Referenz für useGT() an.

Übersetzen von Zeichenketten

Warum kann ich das `llms` Array nicht direkt importieren?

Was ist, wenn ich dynamische Inhalte übersetzen muss?

Auf dieser Seite