Next.js uygulamaları için uluslararasılaştırma (i18n) konusunda en iyi çözüm

Nasıl çalışır

Dünya daha da küreselleştikçe, web geliştiricilerinin farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilen uygulamalar oluşturması 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)dır.

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

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

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

Next.js uygulamanızda uluslararasılaştırmayı (i18n) uygulamak için önce bir i18n kütüphanesi seçeceğiz. Birkaç popüler kütüphane var, bunlar arasında next-intl yer alıyor. Ancak bu örnekte TacoTranslate kullanacağız.

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

Terminalinizde npm kullanarak bunu yükleyelim:

npm install tacotranslate

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

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

TacoTranslate uygulama UI’sinde 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, read/write anahtarı ise secret olarak adlandırdığımız anahtardı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 ortam değişkeni daha ekleyeceğiz: TACOTRANSLATE_DEFAULT_LOCALE ve TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan geri dönüş (fallback) yerel ayar kodu. Bu örnekte bunu İngilizce için en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Metinlerinizin saklanacağı “klasör”, örneğin web sitenizin URL’si. Kaynaklar hakkında daha fazlasını burada okuyun.

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

Adım 3: TacoTranslate'i Kurma

TacoTranslate'i uygulamanızla entegre etmek için, ö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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Kısa süre içinde TACOTRANSLATE_API_KEY otomatik olarak tanımlanacak.

İstemciyi ayrı bir dosyada oluşturmak, daha sonra tekrar kullanmayı kolaylaştırır. Şimdi, özel /pages/_app.tsx kullanarak TacoTranslate sağlayıcısını ekleyeceğiz.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Zaten özel pageProps ve _app.tsx varsa, lütfen tanımı yukarıdaki özellikler ve kod ile genişletin.

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

TacoTranslate çevirilerinizin sunucu tarafında render edilmesine olanak tanır. Bu, çevrilmemiş içeriğin önce bir anlık görünmesi yerine çevrilmiş içeriği anında göstererek kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca istemci tarafında ağ isteklerini atlayabiliriz, çünkü ihtiyacımız olan tüm çeviriler zaten elimizde.

İlk olarak /next.config.js dosyasını oluşturacağız veya değiştireceğiz.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Kurulumunuza uyacak şekilde isProduction kontrolünü değiştirin. Eğer true, TacoTranslate genel API anahtarını ortaya çıkaracaktır. Eğer yerel, test veya staging ortamındaysak (isProduction is false), yeni dizelerin çeviri için gönderildiğinden emin olmak amacıyla gizli read/write API anahtarını kullanacağız.

Şimdiye kadar Next.js uygulamasını yalnızca desteklenen dillerin bir listesiyle yapılandırdık. Bir sonraki adım, tüm sayfalarınız için çevirileri almak olacak. Bunu yapmak için gereksinimlerinize göre getTacoTranslateStaticProps veya getTacoTranslateServerSideProps kullanacaksınız.

Bu fonksiyonlar üç argüman alır: Bir Next.js Static Props Context nesnesi, TacoTranslate yapılandırması ve isteğe bağlı Next.js özellikleri. Şunu unutmayın ki, getTacoTranslateStaticProps içindeki revalidate varsayılan olarak 60 olarak ayarlanmıştır; böylece çevirileriniz güncel kalır.

Herhangi birini bir sayfada kullanmak için, örneğin /pages/hello-world.tsx adlı bir sayfa dosyanız olduğunu varsayalım.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

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

Artık tüm React bileşenlerinizdeki metinleri çevirmek için Translate bileşenini kullanabiliyor olmalısınız.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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

İşimiz bitti! Next.js uygulamanız artık herhangi bir dizeyi Translate bileşenine eklediğinizde otomatik olarak çevrilecek. API anahtarında read/write iznine sahip ortamlarda yeni çevrilecek dizeler oluşturulabileceğini unutmayın. Canlıya geçmeden önce yeni dizeleri ekleyip üretim uygulamanızı böyle bir API anahtarıyla test edebileceğiniz kapalı ve güvenli bir staging ortamı bulundurmanızı öneririz. Bu, gizli API anahtarınızın çalınmasını ve çeviri projenizin yeni, alakasız dizeler eklenerek şişmesini ö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 App 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!