Како да се имплементира интернационализација во Next.js апликација која ја користи App Router

Како светот станува сè по глобализиран, сè повеќе е важно за веб-развојувачите да создаваат апликации кои можат да им служат на корисници од различни земји и култури. Еден од клучните начини за постигнување на ова е преку интернационализација (i18n), која ви овозможува да го прилагодите вашиот апликација на различни јазици, валути и формати на датум.

Во овој напис, ќе разгледаме како да додадете интернационализација во вашата React Next.js апликација, со серверско прикажување (server side rendering). TL;DR: Погледнете го целосниот пример тука.

Овој водич е за Next.js апликации кои користат App Router.
Доколку користите Pages Router, погледнете го овој водич.

Чекор 1: Инсталирајте и18н библиотека

За да ја имплементирате интернационализацијата во вашата Next.js апликација, прво ќе избереме i18n библиотека. Постојат неколку популарни библиотеки, вклучувајќи next-intl. Во овој пример, сепак, ќе го користиме TacoTranslate.

TacoTranslate автоматски ги преведува вашите низи на кој било јазик користејќи најсовремена вештачка интелигенција, и ве ослободува од досадното управување со JSON фајлови.

Ајде да ја инсталираме преку npm во вашиот терминал:

npm install tacotranslate

Чекор 2: Креирајте бесплатен TacoTranslate акаунт

Сега кога го имате инсталирано модулот, време е да креирате ваш профил на TacoTranslate, проект за превод и поврзани API клучеви. Креирајте профил тука. Бесплатно е и не бара додавање на кредитна картичка.

Во интерфејсот на апликацијата TacoTranslate, направете проект и одете на табот за API клучеви. Создадете еден read клуч и еден read/write клуч. Ќе ги зачуваме како променливи на средината. read клучот го нарекуваме public а read/write клучот е secret. На пример, можете да ги додадете во .env датотека во коренот на вашиот проект.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Внимавајте никогаш да не го откриете тајниот read/write API клуч во производствените околини на клиентската страна.

Ќе додадеме уште две променливи на средината: TACOTRANSLATE_DEFAULT_LOCALE и TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Стандардниот код на лајкот за враќање. Во овој пример, ќе го поставиме на en за англиски.
• TACOTRANSLATE_ORIGIN: „Фолдерот“ каде што ќе се чуваат твоите стрингови, како на пример URL-то на твојата веб-страница. Дознај повеќе за origins тука.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Чекор 3: Поставување на TacoTranslate

За да интегрирате TacoTranslate со вашата апликација, ќе треба да креирате клиент користејќи ги API клучевите од претходно. На пример, креирајте фајл именуван /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;

Ние наскоро автоматски ќе ги дефинираме TACOTRANSLATE_API_KEY и TACOTRANSLATE_PROJECT_LOCALE.

Креирањето на клиентот во посебен фајл го прави лесно неговото повторно користење подоцна. getLocales е само помошна функција со вградено ракување со грешки. Сега, креирајте фајл со име /app/[locale]/tacotranslate.tsx, каде што ќе ја имплементираме 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>
	);
}

Внимавајте на 'use client'; што укажува дека ова е клиентски компонент.

Со сега кога контекст провајдерот е подготвен, создадете фајл наречен /app/[locale]/layout.tsx, главниот layout во нашата апликација. Имајте на ум дека овој патек има фолдер кој ги користи Dynamic Routes, каде што [locale] е динамичкиот параметар.

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>
	);
}

Првата работа што треба да се забележи тука е дека го користиме нашиот Dynamic Route параметар [locale] за вчитување преводи за тој јазик. Дополнително, generateStaticParams се грижи сите кодови на локации што ги имате активирано за вашиот проект да бидат предгенерирани.

Сега, ајде да ја изградиме нашата прва страница! Креирајте датотека со име /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!" />
	);
}

Обратете внимание на променливата revalidate која му кажува на Next.js да ја пресоздаде страницата по 60 секунди и да ги одржува вашите преводи ажурни.

Чекор 4: Имплементација на серверско рендерирање

TacoTranslate поддржува серверска страна на рендерирање. Ова значително го подобрува корисничкото искуство со прикажување преведената содржина веднаш, наместо прво да се покаже краток миг на непреведена содржина. Покрај тоа, можеме да ја прескокнеме мрежната барање на клиентот, бидејќи веќе ги имаме преводите што ни се потребни за страницата која ја гледа корисникот.

За да поставите серверско рендерирање, создадете или изменете /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};
};

Изменете ја проверката isProduction според вашата поставка. Ако е true, TacoTranslate ќе го прикаже јавниот API клуч. Ако сме во локална, тест или стрејџинг средина (isProduction is false), ќе го користиме тајниот API клуч read/write за да се осигураме дека новите стрингови се испратени за превод.

За да осигуриме дека рутирањето и пренасочувањето функционираат како што се очекува, ќе треба да креираме датотека со име /middleware.ts. Со користење на Middleware, можеме да ги пренасочиме корисниците кон страници прикажани на нивниот префериран јазик.

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);
}

Се осигурајте да го поставите matcher согласно со документот за Next.js Middleware.

На клиентската страна, можете да го измените колачето locale за да ја промените преферираната јазична поставка на корисникот. Ве молиме видете целосниот примерок на кодот за идеи како да го направите тоа!

Чекор 5: Објави и тестирај!

Готови сме! Вашата React апликација сега автоматски ќе се преведува кога ќе додадете било какви низа во Translate компонентата. Имајте на ум дека само околини со read/write дозволи на API клучот ќе можат да креираат нови низи за превод. Препорачуваме да имате затворена и безбедна тест средина каде што можете да ја тестирате вашата продукциска апликација со таков API клуч, додавајќи нови низи пред да ја поставите во живо. Ова ќе спречи некој да го украде вашиот таен API клуч и потенцијално да го зголеми проектот за превод со додавање нови, несродни низи.

Бидете сигурни да погледнете го целосниот пример на нашиот GitHub профил. Таму, исто така, ќе најдете пример како да го направите ова користејќи го Pages Router! Ако наидете на било какви проблеми, слободно контактирајте не, и со задоволство ќе ви помогнеме.

TacoTranslate ви овозможува автоматска локализација на вашите React апликации брзо на и од било кој јазик. Започнете денес!