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

Khi thế giới 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 càng trở nên quan trọng. Một trong những cách chủ chốt để đạt được điều này là quốc tế hóa (i18n), cho phép bạn điều chỉnh ứng dụng của mình cho các ngôn ngữ, đơn vị tiền tệ và định dạng ngày tháng khác nhau.

Trong bài viết này, chúng tôi sẽ tìm hiểu cách thêm quốc tế hóa vào ứng dụng React Next.js của bạn, kèm theo kết xuất phía máy chủ (server side rendering). 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 vào đó.

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 tôi 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 AI tiên tiến, và giúp bạn thoát khỏi việc quản lý các tệp JSON nhàm chán.

Hãy cài đặt nó bằng npm trong terminal của bạn:

npm install tacotranslate

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

Bây giờ bạn đã cài đặt mô-đun, đã đến lúc tạo tài khoản TacoTranslate, tạo một dự án dịch và các khóa API liên quan. Tạo tài khoản tại đâ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, hãy tạo một dự án và chuyển tới tab API keys. Tạo một khóa read và một khóa read/write. Chúng tôi sẽ lưu chúng dưới dạng biến môi trường. Khóa read chính là cái mà chúng tôi 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 không bao giờ để lộ khóa API bí mật read/write trong 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ã locale dự phòng mặc định. Trong ví dụ này, chúng tôi sẽ đặt nó là en cho tiếng Anh.
• TACOTRANSLATE_ORIGIN: “folder” 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 ở đây.

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

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

Để tích hợp TacoTranslate vào ứng dụng của bạn, bạn sẽ cần tạo một client sử dụng các khóa API từ trước. Ví dụ, tạo một tệp có tên /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 chốc lát.

Tạo client trong một tệp riêng sẽ giúp dễ 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 tệp có tên /app/[locale]/tacotranslate.tsx, nơi chúng ta sẽ triển khai provider 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>
	);
}

Lưu ý 'use client'; cho biết đây là một thành phần phía client.

Khi bộ cung cấp ngữ cảnh đã sẵn sàng, hãy tạo một tệp 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 tôi đang sử dụng tham số Dynamic Route [locale] để lấy bản dịch cho ngôn ngữ đó. Ngoài ra, generateStaticParams đảm bảo rằng tất cả mã locale bạn đã kích hoạt cho dự án được kết xuất trước.

Bây giờ, hãy xây dựng trang đầu tiên của chúng ta! 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 Next.js biết phải xây dựng lại trang sau 60 giây và giữ cho các bản dịch của bạn luô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 trải nghiệm người dùng đáng kể bằng cách hiển thị nội dung đã được dịch ngay lập tức, thay vì để xuất hiện một khoảnh khắc nội dung chưa được dịch trước. Ngoài ra, chúng ta có thể bỏ qua các yêu cầu mạng ở 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ủ, 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};
};

Điều chỉnh 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 ở môi trường cục bộ, thử nghiệm hoặc staging (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 định tuyến và chuyển hướng hoạt động như mong đợi, chúng ta cần tạo một tệp 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ữ ưa thích của họ.

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 đảm bảo thiết lập matcher phù hợp với tài liệu về Middleware của Next.js.

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

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

Xong rồi! Ứng dụng React của bạn sẽ được dịch tự động khi bạn thêm bất kỳ chuỗi nào vào một thành phần Translate. Lưu ý rằng chỉ các 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ị bạn nên có một môi trường staging khép kín và được bảo mật, nơi bạn có thể kiểm thử ứng dụng production 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 đưa lên môi trường chính thức. Điều này sẽ ngăn chặn bất kỳ ai lấy cắp khóa API bí mật của bạn, và có thể làm phình to dự án dịch thuật của bạn bằng cách thêm các chuỗi mới, không liên quan.

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!