Intlayer ve Next.js Sayfa Yönlendirici ile uluslararasılaştırma (i18n) başlangıç kılavuzu

Intlayer Nedir?

Intlayer, modern web uygulamalarında çok dilli desteği basitleştirmek için tasarlanmış yenilikçi, açık kaynaklı bir uluslararasılaştırma (i18n) kütüphanesidir. Geleneksel Sayfa Yönlendirici ile Next.js framework'ü ile sorunsuz bir şekilde entegre olur.

Intlayer ile şunları yapabilirsiniz:

• Çevirileri bildirimsel sözlükler kullanarak kolayca yönetin bileşen düzeyinde.
• Meta verileri, rotaları ve içeriği dinamik olarak yerelleştirin.
• TypeScript desteği sağlayın, otomatik tamamlama ve hata algılama ile geliştirin.
• Gelişmiş özelliklerden yararlanın, dinamik yerel algılama ve anahtarlama gibi.

Intlayer, Next.js 12, 13, 14 ve 15 ile uyumludur. App Router kullanıyorsanız, App Router kılavuzuna bakın. Next.js 15 için bu kılavuza bakın.

Sayfa Yönlendirici Kullanarak Next.js Uygulamasında Intlayer Kurulumu Adım Adım Kılavuzu

Adım 1: Bağımlılıkları Kurma

Tercih ettiğiniz paket yöneticisini kullanarak gerekli paketleri kurun:

npm install intlayer next-intlayer

• intlayer

  Yapılandırma yönetimi, çeviri, içerik bildirimi, derleme ve CLI komutları için uluslararasılaştırma araçları sağlayan çekirdek paket.

• next-intlayer

  Intlayer'ı Next.js ile entegre eden paket. Next.js için bağlam sağlayıcıları ve kancalar sağlar. Ayrıca, Intlayer'ı Webpack veya Turbopack ile entegre etmek için Next.js eklentisini içerir, ayrıca kullanıcının tercih ettiği yerel ayarı algılamak, çerezleri yönetmek ve URL yönlendirmesini işlemek için middleware içerir.

Adım 2: Projenizi Yapılandırma

Uygulamanızın desteklediği dilleri tanımlamak için bir yapılandırma dosyası oluşturun:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Diğer yerel ayarlarınızı buraya ekleyin    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Bu yapılandırma dosyası aracılığıyla, yerelleştirilmiş URL'ler, middleware yönlendirmesi, çerez adları, içerik bildirimlerinizin konumu ve uzantısı, Intlayer günlüklerinin konsolda devre dışı bırakılması ve daha fazlasını ayarlayabilirsiniz. Kullanılabilir parametrelerin tam listesi için yapılandırma dokümantasyonuna bakın.

Adım 3: Next.js Yapılandırmasında Intlayer'ı Entegre Etme

Next.js kurulumunuzu Intlayer ile uyumlu hale getirin:

import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {  // Mevcut Next.js yapılandırmanız};export default withIntlayer(nextConfig);

withIntlayer() Next.js eklentisi, Intlayer'ı Next.js ile entegre etmek için kullanılır. İçerik bildirim dosyalarının oluşturulmasını sağlar ve bunları geliştirme modunda izler. Intlayer ortam değişkenlerini Webpack veya Turbopack ortamlarında tanımlar. Ayrıca, performansı optimize etmek ve sunucu bileşenleriyle uyumluluğu sağlamak için takma adlar sağlar. withIntlayer() Next.js eklentisi promise tabanlı bir fonksiyondur.

Adım 4: Yerel Algılama için Middleware Kurulumu

Kullanıcının tercih ettiği yerel ayarı otomatik olarak algılamak ve işlemek için middleware kurun:

export { intlayerMiddleware as middleware } from "next-intlayer/middleware";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

Eşleştirici parametresini uygulamanızın rotalarına uyacak şekilde uyarlayın. Daha fazla detay için Next.js dokümantasyonunda eşleştiriciyi yapılandırma bölümüne bakın.

Adım 5: Dinamik Yerel Rotalar Tanımlama

Kullanıcının yerel ayarına göre yerelleştirilmiş içerik sunmak için dinamik yönlendirmeyi uygulayın.

1. Yerel Ayar Özel Sayfalar Oluşturma:

   Ana sayfa dosyanızı [locale] dinamik segmentini içerecek şekilde yeniden adlandırın.

   bash

   Kodu kopyala

   Kodu panoya kopyala

   mv src/pages/index.tsx src/pages/[locale]/index.tsx

2. Yerelleştirmeyi İşlemek için _app.tsx'yi Güncelleme:

   _app.tsx'nizi Intlayer sağlayıcılarını içerecek şekilde değiştirin.

   src/pages/_app.tsx

   Kodu kopyala

   Kodu panoya kopyala

   import type { FC } from "react";import type { AppProps } from "next/app";import { IntlayerClientProvider } from "next-intlayer";const App = FC<AppProps>({ Component, pageProps }) => {  const { locale } = pageProps;  return (    <IntlayerClientProvider locale={locale}>      <Component {...pageProps} />    </IntlayerClientProvider>  );}export default MyApp;

3. Yolları ve Özellikleri İşlemek için getStaticPaths ve getStaticProps Kurulumu:

   [locale]/index.tsx'nizde farklı yerel ayarları işlemek için yolları ve özellikleri tanımlayın.

   src/pages/[locale]/index.tsx

   Kodu kopyala

   Kodu panoya kopyala

   import type { FC } from "react";import type { GetStaticPaths, GetStaticProps } from "next";import { type Locales, getConfiguration } from "intlayer";const HomePage: FC = () => <div>{/* İçeriğiniz burada */}</div>;export const getStaticPaths: GetStaticPaths = () => {  const { internationalization } = getConfiguration();  const { locales } = internationalization;  const paths = locales.map((locale) => ({    params: { locale },  }));  return { paths, fallback: false };};export const getStaticProps: GetStaticProps = ({ params }) => {  const locale = params?.locale as string;  return {    props: {      locale,    },  };};export default HomePage;

getStaticPaths ve getStaticProps, Next.js Sayfa Yönlendirici'de uygulamanızın tüm yerel ayarlar için gerekli sayfaları önceden oluşturmasını sağlar. Bu yaklaşım, çalışma zamanı hesaplamasını azaltır ve iyileştirilmiş bir kullanıcı deneyimi sağlar. Daha fazla detay için Next.js'in getStaticPaths ve getStaticProps dokümantasyonuna bakın.

Adım 6: İçeriğinizi Bildirin

Çevirileri depolamak için içerik bildirimlerinizi oluşturun ve yönetin.

import { t, type Dictionary } from "intlayer";const homeContent = {  key: "home",  content: {    title: t({      en: "Welcome to My Website",      fr: "Bienvenue sur mon site Web",      es: "Bienvenido a mi sitio web",    }),    description: t({      en: "Get started by editing this page.",      fr: "Commencez par éditer cette page.",      es: "Comience por editar esta página.",    }),  },} satisfies Dictionary;export default homeContent;

İçerik bildirim hakkında daha fazla bilgi için içerik bildirim kılavuzuna bakın.

Adım 7: Kodunuzda İçeriği Kullanın

Çevirilmiş içerik görüntülemek için uygulamanız boyunca içerik sözlüklerinize erişin.

import type { FC } from "react";import { useIntlayer } from "next-intlayer";import { ComponentExample } from "@components/ComponentExample";const HomePage: FC = () => {  const content = useIntlayer("home");  return (    <div>      <h1>{content.title}</h1>      <p>{content.description}</p>      <ComponentExample />      {/* Ek bileşenler */}    </div>  );};// ... getStaticPaths ve getStaticProps dahil geri kalan kodexport default HomePage;

import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ComponentExample: FC = () => {  const content = useIntlayer("component-example"); // İlgili içerik bildirimi oluşturduğunuzdan emin olun  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

Çevirileri string niteliklerinde kullanmak istediğinizde (örneğin alt, title, href, aria-label), fonksiyonun değerini şu şekilde çağırın:

jsx

Kodu kopyala

Kodu panoya kopyala

<img src={content.image.src.value} alt={content.image.value} />

useIntlayer kancası hakkında daha fazla bilgi edinmek için dokümantasyona bakın.

(İsteğe Bağlı) Adım 8: Meta verilerinizin uluslararasılaştırılması

Sayfanızın başlığı gibi meta verilerinizi uluslararasılaştırmak istiyorsanız, Next.js Sayfa Yönlendirici tarafından sağlanan getStaticProps fonksiyonunu kullanabilirsiniz. İçinde, meta verilerinizi çevirmek için getIntlayer fonksiyonundan içeriği alabilirsiniz.

import { type Dictionary, t } from "intlayer";import { type Metadata } from "next";const metadataContent = {  key: "page-metadata",  content: {    title: t({      en: "Create Next App",      fr: "Créer une application Next.js",      es: "Crear una aplicación Next.js",    }),    description: t({      en: "Generated by create next app",      fr: "Généré par create next app",      es: "Generado por create next app",    }),  },} satisfies Dictionary<Metadata>;export default metadataContent;

import { GetStaticPaths, GetStaticProps } from "next";import { getIntlayer, getMultilingualUrls } from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps {  locale: string;  metadata: {    title: string;    description: string;  };  multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({  metadata,  multilingualUrls,  locale,}) => {  const content = useIntlayer("page");  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />        {/* SEO için hreflang etiketleri oluşturun */}        {Object.entries(multilingualUrls).map(([lang, url]) => (          <link key={lang} rel="alternate" hrefLang={lang} href={url} />        ))}        <link rel="canonical" href={multilingualUrls[locale]} />      </Head>      {/* Sayfa içeriği */}      <main>{/* Sayfa içeriğiniz burada */}</main>    </div>  );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({  params,}) => {  const locale = params?.locale as string;  const metadata = getIntlayer("page-metadata", locale);  /**   * Her yerel ayar için tüm URL'leri içeren bir nesne oluşturur.   *   * Örnek:   * ```ts   *  getMultilingualUrls('/about');   *   *  // Döndürür   *  // {   *  //   en: '/about',   *  //   fr: '/fr/about',   *  //   es: '/es/about',   *  // }   * ```   */  const multilingualUrls = getMultilingualUrls("/");  return {    props: {      locale,      metadata,      multilingualUrls,    },  };};export default HomePage;// ... getStaticPaths dahil geri kalan kod

Not: next-intlayer'dan içe aktarılan getIntlayer fonksiyonu, içeriğinizi görsel düzenleyici ile entegrasyon için IntlayerNode'a sarılmış olarak döndürür. Aksine, intlayer'dan içe aktarılan getIntlayer fonksiyonu içeriğinizi doğrudan ek özellikler olmadan döndürür.

Alternatif olarak, meta verilerinizi bildirmek için getTranslation fonksiyonunu kullanabilirsiniz. Ancak, içerik bildirim dosyalarını kullanmak, meta verilerinizin çevirisini otomatikleştirmek ve içeriği bir noktada harici hale getirmek için önerilir.

import { GetStaticPaths, GetStaticProps } from "next";import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps {  locale: string;  metadata: {    title: string;    description: string;  };  multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => {  const content = useIntlayer("page");  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />        {/* SEO için hreflang etiketleri oluşturun */}        {Object.entries(multilingualUrls).map(([lang, url]) => (          <link            key={lang}            rel="alternate"            hrefLang={lang}            href={url}          />        ))}        <link rel="canonical" href={multilingualUrls[locale]} />      </Head>      {/* Sayfa içeriği */}      <main>        {/* Sayfa içeriğiniz burada */}      </main>    </div>  );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({  params}) => {  const locale = params?.locale as string;  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);  const metadata = {    title: t<string>({      en: "My title",      fr: "Mon titre",      es: "Mi título",    }),    description: t({      en: "My description",      fr: "Ma description",      es: "Mi descripción",    }),  };  const multilingualUrls = getMultilingualUrls("/");  return {    props: {      locale,      metadata,      multilingualUrls,    },  };};export default HomePage;// ... getStaticPaths dahil geri kalan kod

Meta veri optimizasyonu hakkında daha fazla bilgi edinmek için resmi Next.js dokümantasyonuna bakın.

(İsteğe Bağlı) Adım 9: İçeriğinizin dilini değiştirme

Next.js'te içeriğinizin dilini değiştirmek için, kullanıcıları uygun yerelleştirilmiş sayfaya yönlendirmek için Link bileşenini kullanmak önerilen yoldur. Link bileşeni, sayfa ön yüklemesini etkinleştirir, bu da tam sayfa yeniden yüklemeden kaçınmaya yardımcı olur.

import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocalePageRouter } from "next-intlayer";import { type FC } from "react";import Link from "next/link";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter();  const { setLocaleCookie } = useLocaleCookie();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <Link            href={getLocalizedUrl(pathWithoutLocale, localeItem)}            hrefLang={localeItem}            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocaleCookie(localeItem)}          >            <span>              {/* Yerel ayar - örn. FR */}              {localeItem}            </span>            <span>              {/* Kendi yerel ayarındaki dil - örn. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Geçerli yerel ayar set edildiğinde dil - örn. Locales.SPANISH set edildiğinde Francés */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* İngilizce'deki dil - örn. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        ))}      </div>    </div>  );};

Alternatif bir yol, useLocale kancası tarafından sağlanan setLocale fonksiyonunu kullanmaktır. Bu fonksiyon, sayfa ön yüklemesine izin vermez ve sayfayı yeniden yükler.

Bu durumda, router.push kullanarak yönlendirme olmadan, sadece sunucu tarafı kodunuz içeriğin yerel ayarını değiştirecektir.

"use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Geri kalan kodconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>Fransızca'ya Geç</button>);

useLocalePageRouter API'si useLocale ile aynıdır. useLocale kancası hakkında daha fazla bilgi edinmek için dokümantasyona bakın.

Dokümantasyon referansları:

• getLocaleName kancası
• getLocalizedUrl kancası
• getHTMLTextDir kancası
• hrefLang özelliği
• lang özelliği
• dir özelliği
• aria-current özelliği

(İsteğe Bağlı) Adım 10: Yerelleştirilmiş Bağlantı Bileşeni Oluşturma

Uygulamanızın navigasyonunun mevcut yerel ayarı saygı göstermesini sağlamak için, özel bir Link bileşeni oluşturabilirsiniz. Bu bileşen, dahili URL'leri otomatik olarak mevcut dille önekler, böylece örneğin Fransızca konuşan bir kullanıcı "Hakkında" sayfasına bir bağlantıya tıkladığında, /fr/hakkinda yerine /hakkindaya yönlendirilir.

Bu davranış birkaç nedenden dolayı kullanışlıdır:

• SEO ve Kullanıcı Deneyimi: Yerelleştirilmiş URL'ler, arama motorlarının dil özel sayfalarını doğru şekilde indekslemesine yardımcı olur ve kullanıcılara tercih ettikleri dilde içerik sağlar.
• Tutarlılık: Uygulamanız boyunca yerelleştirilmiş bir bağlantı kullanarak, navigasyonun mevcut yerel ayar içinde kalmasını garanti edersiniz, beklenmedik dil anahtarlarını önlersiniz.
• Bakım Kolaylığı: URL yönetim mantığını tek bir bileşende merkezileştirmek, kod tabanınızı yönetmeyi ve uygulamanız büyüdükçe genişletmeyi basitleştirir.

Aşağıda, TypeScript'te yerelleştirilmiş bir Link bileşeninin uygulanması bulunmaktadır:

"use client";import { getLocalizedUrl } from "intlayer";import NextLink, { type LinkProps as NextLinkProps } from "next/link";import { useLocale } from "next-intlayer";import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";/** * Verilen bir URL'nin harici olup olmadığını kontrol eden yardımcı fonksiyon. * URL http:// veya https:// ile başlıyorsa, harici olarak kabul edilir. */export const checkIsExternalLink = (href?: string): boolean =>  /^https?:\/\//.test(href ?? "");/** * Href özelliğini mevcut yerel ayar temelinde uyarlayan özel bir Link bileşeni. * Dahili bağlantılar için, `getLocalizedUrl` kullanarak URL'yi yerel ayar ile önekler (örneğin, /fr/hakkinda). * Bu, navigasyonun aynı yerel ayar bağlamında kalmasını sağlar. */export const Link = forwardRef<  HTMLAnchorElement,  PropsWithChildren<NextLinkProps>>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {  const { locale } = useLocale();  const isExternalLink = checkIsExternalLink(href.toString());  // Bağlantı dahili ise ve geçerli bir href sağlanmışsa, yerelleştirilmiş URL'yi alın.  const hrefI18n: NextLinkProps["href"] =    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;  return (    <NextLink href={hrefI18n} ref={ref} {...props}>      {children}    </NextLink>  );});Link.displayName = "Link";

Nasıl Çalışır

• Harici Bağlantıları Algılama:
  Yardımcı fonksiyon checkIsExternalLink, bir URL'nin harici olup olmadığını belirler. Harici bağlantılar değişmeden bırakılır çünkü yerelleştirmeye ihtiyaçları yoktur.

• Mevcut Yerel Ayarı Alma:
  useLocale kancası mevcut yerel ayarı sağlar (örneğin, Fransızca için fr).

• URL'yi Yerelleştirme:
  Dahili bağlantılar (yani harici olmayan) için, getLocalizedUrl kullanarak URL'yi otomatik olarak mevcut yerel ayar ile önekler. Bu, kullanıcınız Fransızca ise, /hakkinda href'ini geçmek onu /fr/hakkindaya dönüştürür.

• Bağlantıyı Döndürme:
  Bileşen, yerelleştirilmiş URL ile bir <a> elementi döndürür, böylece navigasyon yerel ayar ile tutarlı olur.

Bu Link bileşenini uygulamanız boyunca entegre ederek, tutarlı ve dil bilincine sahip bir kullanıcı deneyimi sürdürürsünüzken aynı zamanda gelişmiş SEO ve kullanılabilirlikten de yararlanırsınız.

(İsteğe Bağlı) Adım 11: Paket Boyutunuzu Optimize Edin

next-intlayer kullanırken, sözlükler varsayılan olarak her sayfa için pakete dahil edilir. Paket boyutunu optimize etmek için, Intlayer isteğe bağlı bir SWC eklentisi sağlar ki bu, useIntlayer çağrılarını akıllıca makrolar kullanarak değiştirir. Bu, sözlüklerin sadece onları gerçekten kullanan sayfalar için paketlere dahil edilmesini sağlar.

Bu optimizasyonu etkinleştirmek için, @intlayer/swc paketini kurun. Kurulduktan sonra, next-intlayer eklentiyi otomatik olarak algılayacak ve kullanacaktır:

npm install @intlayer/swc --save-dev

Not: Bu optimizasyon sadece Next.js 13 ve üzeri için kullanılabilir.

Not: Bu paket varsayılan olarak kurulmaz çünkü SWC eklentileri Next.js'te hala deneyseldir. Gelecekte değişebilir.

TypeScript Yapılandırma

Intlayer, TypeScript'ten faydalanmak ve kod tabanınızı daha güçlü hale getirmek için modül genişletmesi kullanır.

TypeScript yapılandırmanızın otomatik olarak oluşturulan türleri içerdiğinden emin olun.

{  // ... Mevcut TypeScript yapılandırmalarınız  "include": [    // ... Mevcut TypeScript yapılandırmalarınız    ".intlayer/**/*.ts", // Otomatik olarak oluşturulan türleri dahil edin  ],}

Git Yapılandırma

Deponuzu temiz tutmak ve oluşturulan dosyaları göndermemek için, Intlayer tarafından oluşturulan dosyaları yok saymanız önerilir.

.gitignore dosyanıza aşağıdaki satırları ekleyin:

# Intlayer tarafından oluşturulan dosyaları yok say.intlayer

VS Code Uzantısı

Intlayer ile geliştirme deneyiminizi geliştirmek için, resmi Intlayer VS Code Uzantısı'nı kurabilirsiniz.

VS Code Marketplace'ten Kurun

Bu uzantı şunları sağlar:

• Çeviri anahtarları için otomatik tamamlama.
• Eksik çeviriler için gerçek zamanlı hata algılama.
• Çevrilmiş içeriğin satır içi önizlemeleri.
• Çevirileri kolayca oluşturmak ve güncellemek için hızlı eylemler.

Uzantının nasıl kullanılacağı hakkında daha fazla detay için, Intlayer VS Code Uzantısı dokümantasyonuna bakın.

Ek Kaynaklar

• Intlayer Dokümantasyonu: GitHub Deposu
• Sözlük Kılavuzu: Sözlük
• Yapılandırma Dokümantasyonu: Yapılandırma Kılavuzu

Bu kılavuzu takip ederek, Sayfa Yönlendirici kullanarak Next.js uygulamanızda Intlayer'ı etkili bir şekilde entegre edebilir, web projeleriniz için sağlam ve ölçeklenebilir uluslararasılaştırma desteği sağlayabilirsiniz.

Daha Fazla Bilgi Edinin

Daha fazla ilerlemek için, görsel düzenleyiciyi uygulayabilir veya içeriğinizi CMS kullanarak harici hale getirebilirsiniz.

Dokümantasyon Geçmişi