Com implementar la internacionalització en una aplicació Next.js que utilitza el App Router
Fes que la teva aplicació React sigui més accessible i arriba a nous mercats amb la internacionalització (i18n).
A mesura que el món es globalitza més, és cada cop més important per als desenvolupadors web crear aplicacions que puguin satisfer les necessitats d’usuaris de diferents països i cultures. Una de les maneres clau d’aconseguir-ho és a través de la internacionalització (i18n), que permet adaptar la teva aplicació a diferents idiomes, monedes i formats de data.
En aquest article, explorarem com afegir la internacionalització a la teva aplicació React Next.js, amb renderitzat del costat del servidor. TL;DR: Vegeu l’exemple complet aquí.
Aquesta guia és per a aplicacions Next.js que utilitzen el App Router.
Si utilitzeu el Pages Router, consulteu aquesta guia en canvi.
Pas 1: Instal·la una biblioteca i18n
Per implementar la internacionalització a la teva aplicació Next.js, primer triarem una biblioteca i18n. N’hi ha diverses populars, incloent next-intl. En aquest exemple, però, utilitzarem TacoTranslate.
TacoTranslate tradueix automàticament les teves cadenes a qualsevol idioma utilitzant IA d’última generació, i et llibera de la tediosa gestió dels fitxers JSON.
Instal·lem-ho amb npm al teu terminal:
npm install tacotranslate
Pas 2: Crea un compte gratuït a TacoTranslate
Ara que ja tens el mòdul instal·lat, és hora de crear el teu compte de TacoTranslate, un projecte de traducció i les claus API associades. Crea un compte aquí. És gratuït i no requereix que afegeixis una targeta de crèdit.
Dins de la interfície d'usuari de l'aplicació TacoTranslate, crea un projecte i navega fins a la pestanya de claus API. Crea una clau read
i una clau read/write
. Les guardarem com a variables d'entorn. La clau read
és la que anomenem public
, i la clau read/write
és secret
. Per exemple, les podries afegir a un fitxer .env
a l'arrel del teu projecte.
TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010
Assegura't de no filtrar mai la clau secreta read/write
de l'API a entorns de producció del costat client.
També afegirem dues variables d’entorn més: TACOTRANSLATE_DEFAULT_LOCALE
i TACOTRANSLATE_ORIGIN
.
TACOTRANSLATE_DEFAULT_LOCALE
: El codi de localització predeterminat de reserva. En aquest exemple, el configurarem aen
per a l’anglès.TACOTRANSLATE_ORIGIN
: La “carpeta” on es desaran les teves cadenes, com per exemple la URL del teu lloc web. Llegeix més sobre els orígens aquí.
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com
Pas 3: Configurant TacoTranslate
Per integrar TacoTranslate amb la teva aplicació, hauràs de crear un client utilitzant les claus API esmentades anteriorment. Per exemple, crea un fitxer anomenat /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;
Definirem automàticament TACOTRANSLATE_API_KEY
i TACOTRANSLATE_PROJECT_LOCALE
properament.
Crear el client en un fitxer separat facilita tornar a utilitzar-lo més endavant. getLocales
és només una funció d'utilitat amb una gestió d'errors integrada. Ara, crea un fitxer anomenat /app/[locale]/tacotranslate.tsx
, on implementarem el proveïdor TacoTranslate
.
'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>
);
}
Fixa't en 'use client';
que indica que aquest és un component del client.
Amb el context provider ja preparat, crea un fitxer anomenat /app/[locale]/layout.tsx
, el layout arrel de la nostra aplicació. Tingues en compte que aquest camí té una carpeta que utilitza Dynamic Routes, on [locale]
és el paràmetre dinàmic.
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>
);
}
La primera cosa a destacar aquí és que estem utilitzant el nostre paràmetre Dynamic Route
[locale]
per obtenir les traduccions d'aquella llengua. A més, generateStaticParams
s'encarrega que tots els codis de localitat que tens activats per al teu projecte es pre-renderitzin.
Ara, construïm la nostra primera pàgina! Crea un fitxer anomenat /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!" />
);
}
Tingueu en compte la variable revalidate
que indica a Next.js que reconstrueixi la pàgina després de 60 segons i mantingui les vostres traduccions actualitzades.
Pas 4: Implementació del renderitzat al costat del servidor
TacoTranslate admet la representació del costat del servidor. Això millora molt l'experiència de l'usuari mostrant el contingut traduït immediatament, en comptes d'un flaix de contingut no traduït primer. A més, podem saltar-nos les peticions de xarxa al client, perquè ja tenim les traduccions que necessitem per a la pàgina que l'usuari està visualitzant.
Per configurar el renderitzat del costat del servidor, crea o modifica /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};
};
Modifica la comprovació isProduction
per adaptar-la a la teva configuració. Si true
, TacoTranslate mostrarà la clau d’API pública. Si som en un entorn local, de prova o staging (isProduction
is false
), utilitzarem la clau d’API secreta read/write
per assegurar-nos que les noves cadenes s’enviïn per a la traducció.
Per assegurar que el ruteig i la redirecció funcionin com s'espera, haurem de crear un fitxer anomenat /middleware.ts
. Utilitzant Middleware, podem redirigir els usuaris a pàgines presentades en l'idioma que prefereixin.
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);
}
Assegura't de configurar el matcher
d'acord amb la documentació de Middleware de Next.js.
Al client, pots modificar la galeta locale
per canviar l'idioma preferit de l'usuari. Consulta el codi complet de l'exemple per a idees sobre com fer-ho!
Pas 5: Implementa i prova!
Ja hem acabat! La teva aplicació React ara es traduirà automàticament quan afegeixis qualsevol cadena a un component Translate
. Tingues en compte que només els entorns amb permisos read/write
a la clau API podran crear noves cadenes per traduir. Recomanem tenir un entorn de proves tancat i segur on puguis provar la teva aplicació de producció amb una clau API d’aquest tipus, afegint noves cadenes abans de posar-la en funcionament. Això evitarà que algú robi la teva clau API secreta i, potencialment, que s’infli el teu projecte de traducció afegint cadenes noves i no relacionades.
Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.
TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!