Next.js uygulamasında Pages Router kullanan bir projede uluslararasılaştırma 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 temel 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 eğitimde, React Next.js uygulamanıza sunucu tarafı render ile uluslararasılaştırma eklemenin yollarını 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şmayı (i18n) uygulamak için önce bir i18n kütüphanesi seçeceğiz. Birkaç popüler kütüphane vardır, bunlar arasında next-intl. Ancak bu örnekte TacoTranslate.

TacoTranslate, en son teknoloji yapay zekâ kullanarak metinlerinizi herhangi bir dile otomatik olarak çevirir ve sizi JSON dosyalarının zahmetli 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, şimdi 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ı 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 bir .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ırmayın.

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 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 fazla bilgi edinin.

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

Adım 3: TacoTranslate Kurulumu

TacoTranslate'ı 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_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 bir /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>
	);
}

Eğer zaten özelleştirilmiş pageProps ve _app.tsx varsa, lütfen tanımı yukarıdaki özellikler ve kodla genişletin.

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

TacoTranslate, çevirilerinizin sunucu tarafında render edilmesine olanak tanır. Bu, çevirilmiş içeriği hemen göstererek, önce çevrilmemiş içeriğin kısa süreli görüntülenmesi yerine kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca, gerekli tüm çevirilere zaten sahip olduğumuz için istemci tarafında ağ isteklerini atlayabiliriz.

Öncelikle /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 herkese açık API anahtarını gösterecektir. 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.

Şu ana kadar Next.js uygulamasında yalnızca desteklenen dillerin listesini ayarladık. Sonraki adım olarak tüm sayfalarınız için çevirileri alacağız. Bunu yapmak için gereksinimlerinize bağlı olarak getTacoTranslateStaticProps veya getTacoTranslateServerSideProps kullanacaksınız.

Bu fonksiyonlar üç argüman alır: Bir Next.js Static Props Context nesnesi, TacoTranslate için yapılandırma ve isteğe bağlı Next.js özellikleri. Dikkat: getTacoTranslateStaticProps üzerindeki revalidate varsayılan olarak 60'a ayarlanmıştır; bu sayede çevirileriniz güncel kalır.

Her iki fonksiyonu da bir sayfada kullanmak için, örneğin /pages/hello-world.tsx gibi 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 dizeleri ç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ınla ve test et!

İşimiz bitti! React uygulamanız artık herhangi bir diziyi Translate bileşenine eklediğinizde otomatik olarak çevrilecek. API anahtarında read/write izinlerine sahip olan ortamlarda yeni çevrilecek dizeler oluşturulabileceğini unutmayın. Üretim uygulamanızı böyle bir API anahtarıyla test edebileceğiniz kapalı ve güvenli bir staging ortamı bulundurmanızı; yeni dizeleri yayına almadan önce eklemenizi öneririz. Bu, hiç kimsenin gizli API anahtarınızı çalmasını ve potansiyel olarak çeviri projenizin alakasız yeni dizelerle şişmesini önleyecektir.

GitHub profilimizdeki tam örneğe mutlaka göz atın. Orada, ayrıca bunu App Router kullanarak nasıl yapacağınıza dair bir örnek de bulacaksınız! Eğer herhangi bir sorunla karşılaşırsanız, iletişime geçmekten çekinmeyin, size yardımcı olmaktan memnuniyet duyarız.

TacoTranslate, React uygulamalarınızı 75'ten fazla dile ve bu dillerden hızlıca otomatik olarak yerelleştirmenize olanak tanır. Hemen başlayın!