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

Dünya daha küreselleştikçe, web geliştiricilerinin farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilecek uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bunu başarmanın temel yollarından biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanızı sağlayan uluslararasılaşma (i18n) yöntemidir.

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

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

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

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

TacoTranslate, ileri teknoloji AI kullanarak dizelerinizi otomatik olarak herhangi bir dile çevirir ve sizi JSON dosyalarının zahmetli yönetiminden kurtarır.

Bunu terminalinizde npm kullanarak kurabilirsiniz:

npm install tacotranslate

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

Modülü kurduğunuza göre, artık TacoTranslate hesabınızı, bir çeviri projesi 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ı ortam değişkenleri olarak kaydedeceğiz. read anahtarı bizim public olarak adlandırdığımız anahtardır ve read/write anahtarı secret olarak adlandırılır. Ö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ı istemci tarafı üretim ortamlarına asla sızdırmadığınızdan emin olun.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan yedek locale kodu. Bu örnekte, bunu İngilizce için en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Dizelerinizin saklanacağı “klasör”, örneğin web sitenizin URL’si. Kökenler hakkında daha fazla bilgi edinin.

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

Adım 3: TacoTranslate Kurulumu

TacoTranslate'ı 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 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;

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

İstemciyi ayrı bir dosyada oluşturmak, daha sonra tekrar kullanmayı kolaylaştırır. getLocales sadece içinde bazı yerleşik hata yönetimi olan bir yardımcı fonksiyondur. Şimdi, TacoTranslate sağlayıcısını uygulayacağımız /app/[locale]/tacotranslate.tsx adında bir dosya oluşturun.

'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.

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 olan [locale]’yi kullanıyor olmamızdır. Ayrıca, generateStaticParams projeniz için etkinleştirdiğiniz tüm yerel kodlarının önceden render edilmesini 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!" />
	);
}

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

Adım 4: Sunucu tarafı render işleminin uygulanması

TacoTranslate, sunucu tarafı renderlamayı destekler. Bu, çevirisi yapılmamış içeriklerin önce bir anlık gösterilmesi yerine, çevrilmiş içeriğin hemen gösterilmesiyle kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca, kullanıcı tarafından görüntülenen sayfa için ihtiyaç duyduğumuz çeviriler zaten elimizde olduğundan, istemcideki ağ isteklerini de atlayabiliriz.

Sunucu tarafı render işlemini kurmak için /next.config.js dosyasını oluşturun veya değiştirin:

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

Yapınıza uygun olarak isProduction kontrolünü değiştirin. Eğer true ise, TacoTranslate genel API anahtarını kullanacaktır. Eğer yerel, test veya staging ortamındaysak (isProduction is false), yeni metinlerin çeviri için gönderilmesini sağlamak üzere gizli read/write API anahtarını kullanacağız.

Yönlendirme ve yeniden yönlendirme beklendiği gibi çalışması 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 şekilde kurduğunuzdan 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ıza dair fikirler için lütfen tam örnek koda bakın!

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

İşlem tamam! React uygulamanız, herhangi bir metni Translate bileşenine eklediğinizde otomatik olarak çevrilecek. Dikkat edin, yalnızca API anahtarında read/write izinlerine sahip ortamlar yeni çevrilecek metinler oluşturabilir. Üretim uygulamanızı böyle bir API anahtarıyla test edebileceğiniz, kapalı ve güvenli bir staging ortamınızın olmasını öneriyoruz; böylece canlıya geçmeden önce yeni metinler ekleyebilirsiniz. Bu, gizli API anahtarınızın çalınmasını önleyecek ve ilgisiz yeni metinlerin eklenerek çeviri projenizin gereksiz yere şişmesini engelleyecektir.

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!