Next.js uygulamasında App Router kullanan bir projede uluslararasılaştırma (i18n) nasıl uygulanır

Dünya giderek daha küreselleştikçe, web geliştiricilerinin farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilen uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bunu başarmanın ana yollarından biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanıza olanak tanıyan uluslararasılaştırma (i18n) işlemidir.

Bu makalede, React Next.js uygulamanıza sunucu tarafı render desteği ile uluslararasılaştırmayı nasıl ekleyeceğimizi inceleyeceğiz. TL;DR: Tam örneği burada görün.

Bu kılavuz, App Router kullanan Next.js uygulamaları içindir.
Eğer Pages Router kullanıyorsanız, bunun yerine bu kılavuza bakın.

Adım 1: Bir i18n kütüphanesi kurun

Next.js uygulamanızda uluslararasılaştırmayı uygulamak için önce bir i18n kütüphanesi seçeceğiz. Birçok popüler kütüphane bulunmaktadır, bunlar arasında next-intl yer almaktadır. Ancak bu örnekte TacoTranslate kullanacağız.

TacoTranslate, en son yapay zeka teknolojisini kullanarak dizelerinizi otomatik olarak herhangi bir dile çevirir ve JSON dosyalarının zahmetli yönetiminden sizi kurtarır.

Terminalinizde npm ile yükleyelim:

npm install tacotranslate

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

Modülü kurduğunuza göre, şimdi TacoTranslate hesabınızı, bir çeviri projesi ve ilgili API anahtarlarını oluşturmanın zamanı geldi. Buradan bir hesap oluşturun. Ücretsizdir ve kredi kartı eklemenizi gerektirmez.

TacoTranslate uygulama arayüzü içinde bir proje oluşturun ve API anahtarları sekmesine gidin. Bir tane read anahtarı ve bir tane read/write anahtarı oluşturun. Bunları ortam değişkenleri olarak kaydedeceğiz. read anahtarı public olarak adlandırdığımız anahtardır ve read/write anahtarı secret anahtarıdır. Örneğin, bunları projenizin kök dizininde bulunan .env dosyasına ekleyebilirsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gizli read/write API anahtarını kesinlikle istemci tarafı üretim ortamlarına sızdırmayın.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan yedek dil kodu. Bu örnekte, İngilizce için en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Stringlerinizin saklanacağı “klasör”, örneğin web sitenizin URL’si. Origin hakkında daha fazla bilgi için burayı okuyun.

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

Adım 3: TacoTranslate Kurulumu

TacoTranslate’i uygulamanızla entegre etmek için, daha önce aldığınız API anahtarlarını kullanarak bir istemci oluşturmanız gerekecek. Örneğin, /tacotranslate-client.js adında 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 otomatik olarak TACOTRANSLATE_API_KEY ve TACOTRANSLATE_PROJECT_LOCALE tanımlanacak.

Client'i ayrı bir dosyada oluşturmak, daha sonra tekrar kullanmayı kolaylaştırır. getLocales ise yerleşik bazı hata yönetimleri olan 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>
	);
}

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

Artık bağlam sağlayıcımız hazır olduğuna göre, /app/[locale]/layout.tsx adında bir dosya oluşturun, bu uygulamamızdaki kök düzenidir. Bu yolun, Dynamic Routes kullanan bir klasörü olduğunu unutmayın; 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] kullanmamızdır. Ayrıca, generateStaticParams projeniz için etkinleştirdiğiniz tüm yerel kodlarının önceden oluşturulmasını sağlamaktadır.

Ş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 işleminin uygulanması

TacoTranslate sunucu tarafı render'ı destekler. Bu, çevrilmemiş içeriğin önce kısa bir süre yanıp sönmesi yerine, çevirilmiş içeriğin hemen gösterilmesiyle kullanıcı deneyimini büyük ölçüde iyileştirir. Ek olarak, kullanıcı tarafından görüntülenen sayfa için gereken çevirilere zaten sahip olduğumuz için istemci tarafında ağ isteklerini atlayabiliriz.

Sunucu tarafı render'ı ayarlamak için, /next.config.js dosyasını oluşturun veya düzenleyin:

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 kontrolünü kurulumunuza uyacak şekilde değiştirin. trueise, TacoTranslate genel API anahtarını ortaya çıkaracaktır. Yerel, test veya hazırlama ortamındaysak (isProduction is false), yeni dizgilerin çeviri için gönderildiğinden emin olmak için gizli read/write API anahtarını kullanacağız.

Yönlendirme ve yeniden yönlendirmelerin 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 belgeleri ile uyumlu olacak şekilde ayarlamayı unutmayın.

İ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ıza dair fikirler için lütfen tam örnek koda bakın!

Adım 5: Yayınla ve test et!

İşimiz bitti! Artık React uygulamanız, herhangi bir metni Translate bileşenine eklediğinizde otomatik olarak çevrilecektir. API anahtarında read/write izinlerine sahip olan ortamların, çevrilecek yeni metinler oluşturabileceğini unutmayın. Canlı yayına geçmeden önce yeni metinler ekleyerek üretim uygulamanızı böyle bir API anahtarıyla test edebileceğiniz kapalı ve güvenli bir staging ortamı oluşturmanızı öneriyoruz. Bu, gizli API anahtarınızın çalınmasını önleyecek ve çeviri projenize alakasız yeni metinlerin eklenerek gereksiz büyümesini engelleyecektir.

Kesinlikle GitHub profilimizdeki tam örneği inceleyin. Orada, bunu Pages Router kullanarak nasıl yapacağınıza dair bir örnek de bulacaksınız! Herhangi bir sorunla karşılaşırsanız, çekinmeden bizimle iletişime geçin, size yardımcı olmaktan mutluluk duyarız.

TacoTranslate, React uygulamalarınızı otomatik olarak her dilden hızlıca yerelleştirmenizi sağlar. Bugün başlayın!