App Router kullanan bir Next.js uygulamasında uluslararasılaştırmayı (i18n) nasıl uygularsınız?

Dünya daha küreselleştikçe, web geliştiricilerinin farklı ülkelerden ve kültürlerden kullanıcıların ihtiyaçlarına hitap edebilen uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bu konuda başarının ana yollarından biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanıza olanak sağlayan uluslararasılaştırma (i18n)'dır.

Bu makalede, React Next.js uygulamanıza sunucu tarafı oluşturma ile nasıl uluslararasılaştırma ekleyeceğimizi inceleyeceğiz. TL;DR: Tam örneği buradan görebilirsiniz.

Bu rehber, App Router kullanan Next.js uygulamaları içindir.
Eğer Pages Router kullanıyorsanız, onun yerine bu rehbere bakın.

Adım 1: Bir i18n kütüphanesi yükleyin

Next.js uygulamanıza uluslararasılaştırma (i18n) eklemek için önce bir i18n kütüphanesi seçeceğiz. next-intl dahil olmak üzere birkaç popüler kütüphane vardır. Ancak bu örnekte, TacoTranslate'ı kullanacağız.

TacoTranslate, ileri teknoloji yapay zeka kullanarak metinlerinizi otomatik olarak herhangi bir dile çevirir ve sizi JSON dosyalarının yorucu yönetiminden kurtarır.

Terminalinizde npm kullanarak yükleyelim:

npm install tacotranslate

Adım 2: Ücretsiz bir TacoTranslate hesabı oluşturun

Modülü yüklediğinize göre, TacoTranslate hesabınızı, bir çeviri projesini ve ilişkili API anahtarlarını oluşturma zamanı. Buradan bir hesap oluşturun. Ücretsizdir ve kredi kartı eklemenizi gerektirmez.

TacoTranslate uygulama arayüzünde bir proje oluşturun ve API anahtarları sekmesine gidin. Bir read anahtarı ve bir read/write anahtarı oluşturun. Bunları çevresel değişkenler olarak kaydedeceğiz. read anahtarına biz public diyoruz, read/write anahtarına ise secret. Örneğin, bunları projenizin kök dizinindeki .env dosyasına ekleyebilirsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gizli read/write API anahtarını asla istemci tarafı üretim ortamlarına sızdırmadığınızdan emin olun.

Ayrıca iki ortam değişkeni daha ekleyeceğiz: TACOTRANSLATE_DEFAULT_LOCALE ve TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan yedek yerel kodu. Bu örnekte İngilizce için bunu en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Metinlerinizin saklanacağı “klasör”, örneğin web sitenizin URL’si. Origin'ler hakkında daha fazlasını buradan okuyun.

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

Adım 3: TacoTranslate'yi Kurma

TacoTranslate'i uygulamanıza entegre etmek için, daha önceki API anahtarlarını kullanarak bir istemci oluşturmanız gerekecek. Örneğin, /tacotranslate-client.js adlı bir dosya oluşturun.

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;

Kısa süre içinde TACOTRANSLATE_API_KEY ve TACOTRANSLATE_PROJECT_LOCALE otomatik olarak tanımlanacaktır.

İstemciyi ayrı bir dosyada oluşturmak, daha sonra tekrar kullanmayı kolaylaştırır. getLocales sadece yerleşik hata işleme içeren bir yardımcı fonksiyondur. Şimdi, /app/[locale]/tacotranslate.tsx adlı bir dosya oluşturun; burada TacoTranslate sağlayıcısını uygulayacağız.

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

Bu bir istemci bileşeni olduğunu belirten 'use client'; ifadesine dikkat edin.

Context sağlayıcısı artık hazır olduğuna göre, uygulamamızdaki kök layout olan /app/[locale]/layout.tsx adlı bir dosya oluşturun. Bu yolun Dynamic Routes kullanan bir klasör içerdiğine dikkat edin; burada [locale] dinamik parametredir.

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

Burada dikkat edilmesi gereken ilk şey, o dil için çevirileri almak üzere Dynamic Route parametremiz [locale]'i kullandığımızdır. Ayrıca, generateStaticParams projeniz için etkinleştirdiğiniz tüm yerel kodların önceden oluşturulmasını sağlıyor.

Şimdi ilk sayfamızı oluşturalım! /app/[locale]/page.tsx adlı bir dosya oluşturun.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Next.js'e sayfayı 60 saniye sonra yeniden oluşturmasını ve çevirilerinizi güncel tutmasını söyleyen revalidate değişkenine dikkat edin.

Adım 4: Sunucu tarafı render'ı uygulama

TacoTranslate sunucu tarafı oluşturmayı (server-side rendering) destekler. Bu, önce çevrilmemiş içeriğin kısa bir an görünmesi yerine çevrilmiş içeriği hemen göstererek kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca, kullanıcının görüntülediği sayfa için gerekli çevirilere zaten sahip olduğumuzdan istemci tarafında ağ isteklerini atlayabiliriz.

Sunucu tarafı render'ı kurmak için /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};
};

Kurulumunuza uyacak şekilde isProduction kontrolünü değiştirin. Eğer true, TacoTranslate genel API anahtarını gösterecektir. Yerel, test veya hazırlık ortamındaysak (isProduction is false) yeni dizelerin çeviri için gönderilmesini sağlamak üzere gizli read/write API anahtarını kullanacağız.

Yönlendirme ve yeniden yönlendirmenin beklendiği gibi çalışmasını sağlamak için, /middleware.ts adlı bir dosya oluşturmamız gerekecek. Middleware kullanarak kullanıcıları tercih ettikleri dilde sunulan sayfalara yönlendirebiliriz.

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 öğesini Next.js Middleware belgelerine uygun olarak ayarladığınızdan emin olun.

İstemci tarafında, kullanıcının tercih ettiği dili değiştirmek için locale çerezini değiştirebilirsiniz. Bunu nasıl yapacağınız konusunda fikir almak için lütfen tam örnek koda bakın!

Adım 5: Yayınlayın ve test edin!

İşimiz bitti! React uygulamanız artık herhangi bir metni Translate bileşenine eklediğinizde otomatik olarak çevrilecek. API anahtarında read/write izinlerine sahip ortamların çevrilecek yeni dizeler oluşturabileceğini unutmayın. Böyle bir API anahtarıyla üretim uygulamanızı test edebileceğiniz kapalı ve güvenli bir staging ortamı oluşturmanızı öneriyoruz; canlıya geçmeden önce yeni dizeleri burada ekleyin. Bu, hiç kimsenin gizli API anahtarınızı çalmasını ve çeviri projenizi yeni, alakasız dizeler ekleyerek gereksiz yere şişirmesini önleyecektir.

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!