Hoe om internasionale ondersteuning te implementeer in ʼn Next.js-toepassing wat die App Router gebruik
Maak jou React-toepassing meer toeganklik en bereik nuwe markte met internasionale aanpassing (i18n).
Namate die wêreld meer geglobaliseer raak, word dit al hoe belangriker vir webontwikkelaars om toepassings te bou wat gebruikers uit verskillende lande en kulture kan akkommodeer. Een van die sleutelmaniere om dit te bereik is deur internasionlisering (i18n), wat jou toelaat om jou toepassing aan te pas by verskillende tale, geldeenhede en datumformate.
In hierdie artikel gaan ons verken hoe om internasionlisering by jou React Next.js-toepassing by te voeg, met bediener-side rendering. TL;DR: Sien die volledige voorbeeld hier.
Hierdie gids is vir Next.js-toepassings wat die App Router gebruik.
As jy die Pages Router gebruik, sien eerder hierdie gids.
Stap 1: Installeer ’n i18n-biblioteek
Om internasionaalmaking in jou Next.js-toepassing te implementeer, gaan ons eers ’n i18n-biblioteek kies. Daar is verskeie gewilde biblioteke, insluitend next-intl. In hierdie voorbeeld gaan ons egter TacoTranslate gebruik.
TacoTranslate vertaal jou stringe outomaties na enige taal met behulp van voorpunt KI, en bevry jou van die vervelige bestuur van JSON-lêers.
Laat ons dit installeer met behulp van npm in jou terminal:
npm install tacotranslate
Stap 2: Skep 'n gratis TacoTranslate-rekening
Nou dat jy die module geïnstalleer het, is dit tyd om jou TacoTranslate-rekening, ’n vertaalprojek, en gekoppelde API-sleutels te skep. Skep ’n rekening hier. Dit is gratis, en vereis nie dat jy ’n kredietkaart byvoeg nie.
Binne die TacoTranslate-toepassingskoppelvlak, skep ’n projek en navigeer na die API-sleutels-oortjie daarvan. Skep een read
sleutel, en een read/write
sleutel. Ons sal dit as omgewingveranderlikes stoor. Die read
sleutel is wat ons public
noem en die read/write
sleutel is secret
. Byvoorbeeld, jy kan dit by ’n .env
lêer in die wortel van jou projek voeg.
TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010
Maak seker dat die geheime read/write
API-sleutel nooit na kliëntekant produksie-omgewings gelek word nie.
Ons sal ook nog twee omgewingveranderlikes byvoeg: TACOTRANSLATE_DEFAULT_LOCALE
en TACOTRANSLATE_ORIGIN
.
TACOTRANSLATE_DEFAULT_LOCALE
: Die standaard terugval-lokale kode. In hierdie voorbeeld sal ons dit open
stel vir Engels.TACOTRANSLATE_ORIGIN
: Die “gids” waar jou stringe geberg sal word, soos die URL van jou webwerf. Lees hier meer oor oorspronge.
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com
Stap 3: Stel TacoTranslate op
Om TacoTranslate met jou toepassing te integreer, moet jy ’n kliënt skep met die API-sleutels wat vroeër genoem is. Skep byvoorbeeld ’n lêer met die naam /tacotranslate-client.js
.
const {default: createTacoTranslateClient} = require('tacotranslate');
const tacoTranslate = createTacoTranslateClient({
apiKey:
process.env.TACOTRANSLATE_SECRET_API_KEY ??
process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
process.env.TACOTRANSLATE_API_KEY,
projectLocale:
process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
? process.env.TACOTRANSLATE_PROJECT_LOCALE
: undefined,
});
module.exports = tacoTranslate;
Ons sal binnekort outomaties TACOTRANSLATE_API_KEY
en TACOTRANSLATE_PROJECT_LOCALE
definieer.
Om die kliënt in ’n aparte lêer te skep maak dit maklik om dit later weer te gebruik. getLocales
is net ’n nutsfunksie met ’n paar ingeboude fouthantering. Skep nou ’n lêer met die naam /app/[locale]/tacotranslate.tsx
, waar ons die TacoTranslate
verskaffer gaan implementeer.
'use client';
import React, {type ReactNode} from 'react';
import {
type TranslationContextProperties,
TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';
export default function TacoTranslate({
locale,
origin,
localizations,
children,
}: TranslationContextProperties & {
readonly children: ReactNode;
}) {
return (
<ImportedTacoTranslate
client={tacoTranslateClient}
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</ImportedTacoTranslate>
);
}
Let op die 'use client';
wat aandui dat dit ’n kliëntkomponent is.
Met die kontekstverskaffer nou gereed, skep 'n lêer met die naam /app/[locale]/layout.tsx
, die wortel-uitleg in ons toepassing. Let daarop dat hierdie pad 'n vouer gebruik wat Dynamic Routes gebruik, waar [locale]
die dinamiese parameter is.
import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';
export async function generateStaticParams() {
const locales = await tacoTranslateClient.getLocales();
return locales.map((locale) => ({locale}));
}
type RootLayoutParameters = {
readonly params: Promise<{locale: Locale}>;
readonly children: ReactNode;
};
export default async function RootLayout({params, children}: RootLayoutParameters) {
const {locale} = await params;
const origin = process.env.TACOTRANSLATE_ORIGIN;
const localizations = await tacoTranslateClient.getLocalizations({
locale,
origins: [origin /* , other origins to fetch */],
});
return (
<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
<body>
<TacoTranslate
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</TacoTranslate>
</body>
</html>
);
}
Die eerste ding om hier op te let is dat ons ons Dynamic Route
parameter [locale]
gebruik om vertalings vir daardie taal te haal. Boonop sorg generateStaticParams
dat al die locale-kodes wat jy vir jou projek geaktiveer het, vooraf-gerender word.
Kom ons bou nou ons eerste bladsy! Skep 'n lêer met die naam /app/[locale]/page.tsx
.
import React from 'react';
import {Translate} from 'tacotranslate/react';
export const revalidate = 60;
export default async function Page() {
return (
<Translate string="Hello, world!" />
);
}
Let op die revalidate
veranderlike wat aan Next.js sê om die bladsy na 60 sekondes weer op te bou en jou vertalings op datum te hou.
Stap 4: Implementering van bediener-kant rendering
TacoTranslate ondersteun bedienerkant rendering. Dit verbeter die gebruikerservaring aansienlik deur vertaalde inhoud onmiddellik te wys, in plaas van eers ’n kort blik van nie-vertaalde inhoud. Daarbenewens kan ons netwerkversoeke aan die kliënt oorslaan, omdat ons reeds die vertalings het wat ons nodig het vir die bladsy wat die gebruiker besigtig.
Om bedienerkant-weergawes op te stel, skep of wysig /next.config.js
:
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = await withTacoTranslate(
{},
{
client: tacoTranslateClient,
isProduction:
process.env.TACOTRANSLATE_ENV === 'production' ||
process.env.VERCEL_ENV === 'production' ||
(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
process.env.NODE_ENV === 'production'),
}
);
// NOTE: Remove i18n from config when using the app router
return {...config, i18n: undefined};
};
Wysig die isProduction
kontrole om by jou opstelling te pas. As dit true
is, sal TacoTranslate die publieke API-sleutel openbaar maak. As ons in ʼn lokale, toets- of staging-omgewing is (isProduction
is false
), sal ons die geheime read/write
API-sleutel gebruik om seker te maak nuwe stringe word gestuur vir vertaling.
Om te verseker dat roetering en herleiding soos verwag werk, sal ons ʼn lêer met die naam /middleware.ts
moet skep. Deur gebruik te maak van Middleware, kan ons gebruikers herlei na bladsye wat in hul voorkeurtaal aangebied word.
import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';
export const config = {
matcher: ['/((?!api|_next|favicon.ico).*)'],
};
export async function middleware(request: NextRequest) {
return tacoTranslateMiddleware(tacoTranslate, request);
}
Maak seker dat jy die matcher
opstel ooreenkomstig die Next.js Middleware-dokumentasie.
Aan die kliëntkant kan jy die locale
koekie verander om die gebruiker se voorkeurtaal aan te pas. Sien asseblief die volledige voorbeeldkode vir idees oor hoe om dit te doen!
Stap 5: Ontplooi en toets!
Ons is klaar! Jou React-toepassing sal nou outomaties vertaal word wanneer jy enige stringe by ʼn Translate
komponent voeg. Neem asseblief kennis dat slegs omgewings met read/write
magte op die API-sleutel nuwe stringe kan skep om vertaal te word. Ons beveel aan om ʼn geslote en veilig gepantserde staging-omgewing te hê waar jy jou produksietoepassing met so ʼn API-sleutel kan toets, en nuwe stringe kan toevoeg voordat dit lewendig gaan. Dit sal voorkom dat enigiemand jou geheime API-sleutel steel, en moontlik jou vertaallynprojek laat aangroei deur nuwe, nie-verwante stringe by te voeg.
Maak seker dat jy die volledige voorbeeld by ons GitHub-profiel nakyk. Daar sal jy ook ’n voorbeeld vind van hoe om dit te doen met die Pages Router ! As jy enige probleme ondervind, voel vry om kontak te maak, en ons sal meer as bly wees om te help.
TacoTranslate laat jou toe om jou React-toepassings vinnig en outomaties van en na enige taal te lokaliseer. Begin vandag nog!