Cách triển khai quốc tế hóa trong ứng dụng Next.js sử dụng App Router

Khi thế giới trở nên ngày càng toàn cầu hóa, việc các nhà phát triển web xây dựng các ứng dụng có thể phục vụ người dùng từ các quốc gia và nền văn hóa khác nhau trở nên càng quan trọng hơn. Một trong những cách chính để đạt được điều này là thông qua quốc tế hóa (i18n), cho phép bạn điều chỉnh ứng dụng của mình cho phù hợp với các ngôn ngữ, tiền tệ và định dạng ngày tháng khác nhau.

Trong bài viết này, chúng ta sẽ khám phá cách thêm quốc tế hóa vào ứng dụng React Next.js của bạn, với kết xuất phía máy chủ. TL;DR: Xem ví dụ đầy đủ tại đây.

Hướng dẫn này dành cho các ứng dụng Next.js sử dụng App Router.
Nếu bạn đang sử dụng Pages Router, hãy xem hướng dẫn này thay thế.

Bước 1: Cài đặt một thư viện i18n

Để triển khai quốc tế hóa trong ứng dụng Next.js của bạn, trước tiên chúng ta sẽ chọn một thư viện i18n. Có một số thư viện phổ biến, bao gồm next-intl. Tuy nhiên, trong ví dụ này, chúng ta sẽ sử dụng TacoTranslate.

TacoTranslate tự động dịch các chuỗi của bạn sang bất kỳ ngôn ngữ nào bằng cách sử dụng AI tiên tiến, và giải phóng bạn khỏi việc quản lý tẻ nhạt các tệp JSON.

Hãy cài đặt nó bằng cách sử dụng npm trong terminal của bạn:

npm install tacotranslate

Bước 2: Tạo một tài khoản TacoTranslate miễn phí

Bây giờ bạn đã cài đặt module, đã đến lúc tạo tài khoản TacoTranslate, một dự án dịch và các khóa API liên quan. Tạo tài khoản tại đây. Việc này miễn phí, và không yêu cầu bạn phải thêm thẻ tín dụng.

Trong giao diện ứng dụng TacoTranslate, tạo một dự án, và điều hướng đến tab khóa API của nó. Tạo một khóa read và một khóa read/write. Chúng ta sẽ lưu chúng dưới dạng biến môi trường. Khóa read là cái mà chúng ta gọi là public và khóa read/write là secret. Ví dụ, bạn có thể thêm chúng vào một tệp .env ở thư mục gốc của dự án.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Hãy chắc chắn rằng không bao giờ tiết lộ khóa API bí mật read/write cho môi trường sản xuất phía client.

Chúng tôi cũng sẽ thêm hai biến môi trường nữa: TACOTRANSLATE_DEFAULT_LOCALE và TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Mã ngôn ngữ dự phòng mặc định. Trong ví dụ này, chúng tôi sẽ đặt nó thành en cho tiếng Anh.
• TACOTRANSLATE_ORIGIN: “Thư mục” nơi các chuỗi của bạn sẽ được lưu trữ, chẳng hạn như URL của trang web của bạn. Đọc thêm về origins tại đây.

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

Bước 3: Thiết lập TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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;

Chúng tôi sẽ tự động định nghĩa TACOTRANSLATE_API_KEY và TACOTRANSLATE_PROJECT_LOCALE trong thời gian sớm nhất.

Tạo client trong một file riêng biệt giúp dễ dàng sử dụng lại sau này. getLocales chỉ là một hàm tiện ích với một số xử lý lỗi tích hợp sẵn. Bây giờ, hãy tạo một file có tên /app/[locale]/tacotranslate.tsx, nơi chúng ta sẽ triển khai TacoTranslate provider.

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

Lưu ý 'use client'; biểu thị rằng đây là một thành phần phía client.

Với context provider giờ đã sẵn sàng, hãy tạo một file có tên /app/[locale]/layout.tsx, là layout gốc trong ứng dụng của chúng ta. Lưu ý rằng đường dẫn này có một thư mục sử dụng Dynamic Routes, trong đó [locale] là tham số động.

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

Điều đầu tiên cần lưu ý ở đây là chúng ta đang sử dụng tham số Dynamic Route [locale] để lấy bản dịch cho ngôn ngữ đó. Thêm vào đó, generateStaticParams đảm bảo tất cả các mã ngôn ngữ bạn đã kích hoạt cho dự án của mình được dựng trước.

Bây giờ, hãy cùng xây dựng trang đầu tiên của bạn! Tạo một tệp có tên /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!" />
	);
}

Lưu ý biến revalidate cho biết Next.js sẽ xây dựng lại trang sau 60 giây và giữ cho các bản dịch của bạn được cập nhật.

Bước 4: Triển khai kết xuất phía máy chủ

TacoTranslate hỗ trợ kết xuất phía máy chủ. Điều này cải thiện đáng kể trải nghiệm người dùng bằng cách hiển thị nội dung đã được dịch ngay lập tức, thay vì để hiện tượng nội dung chưa được dịch xuất hiện thoáng qua trước tiên. Thêm vào đó, chúng ta có thể bỏ qua các yêu cầu mạng trên phía client, vì chúng ta đã có sẵn các bản dịch cần thiết cho trang mà người dùng đang xem.

Để thiết lập kết xuất phía máy chủ, hãy tạo hoặc chỉnh sửa /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};
};

Sửa đổi kiểm tra isProduction cho phù hợp với thiết lập của bạn. Nếu true, TacoTranslate sẽ hiển thị khóa API công khai. Nếu chúng ta đang ở trong môi trường cục bộ, thử nghiệm hoặc dàn dựng (isProduction is false), chúng ta sẽ sử dụng khóa API bí mật read/write để đảm bảo các chuỗi mới được gửi để dịch.

Để đảm bảo routing và chuyển hướng hoạt động như mong muốn, chúng ta cần tạo một file có tên /middleware.ts. Sử dụng Middleware, chúng ta có thể chuyển hướng người dùng đến các trang được hiển thị bằng ngôn ngữ mà họ ưa thích.

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

Hãy chắc chắn thiết lập matcher phù hợp với tài liệu Middleware của Next.js.

Trên client, bạn có thể thay đổi cookie locale để thay đổi ngôn ngữ ưu tiên của người dùng. Vui lòng xem mã ví dụ hoàn chỉnh để biết ý tưởng về cách thực hiện điều này!

Bước 5: Triển khai và kiểm tra!

Chúng ta đã hoàn thành! Ứng dụng React của bạn sẽ tự động được dịch khi bạn thêm bất kỳ chuỗi nào vào Translate component. Lưu ý rằng chỉ những môi trường có quyền read/write trên khóa API mới có thể tạo các chuỗi mới để dịch. Chúng tôi khuyến nghị có một môi trường staging đóng và bảo mật, nơi bạn có thể thử nghiệm ứng dụng sản xuất của mình với một khóa API như vậy, thêm các chuỗi mới trước khi triển khai chính thức. Điều này sẽ ngăn chặn việc ai đó đánh cắp khóa API bí mật của bạn và có thể làm phình to dự án dịch của bạn bằng cách thêm các chuỗi mới không liên quan.

Hãy chắc chắn rằng bạn xem ví dụ hoàn chỉnh trên hồ sơ GitHub của chúng tôi. Ở đó, bạn cũng sẽ tìm thấy một ví dụ về cách làm việc này sử dụng Pages Router! Nếu bạn gặp bất kỳ vấn đề nào, hãy thoải mái liên hệ, và chúng tôi sẽ rất vui được hỗ trợ bạn.

TacoTranslate cho phép bạn tự động bản địa hóa các ứng dụng React của mình nhanh chóng sang và từ bất kỳ ngôn ngữ nào. Bắt đầu ngay hôm nay!