Intlayer kullanarak Next.js 16 web sitenizi çevirin | Uluslararasılaştırma (i18n)

GitHub'daki Uygulama Şablonuna bakın.

İçindekiler

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. Intlayer, güçlü App Router dahil olmak üzere en son Next.js 16 framework'ü ile sorunsuz bir şekilde entegre olur. Verimli render için Sunucu Bileşenleri (Server Components) ile çalışacak şekilde optimize edilmiştir ve Turbopack ile tam uyumludur.

Intlayer ile şunları yapabilirsiniz:

• Bileşen düzeyinde bildirimsel sözlükler kullanarak çevirileri kolayca yönetin.
• Meta verileri, rotaları ve içeriği dinamik olarak yerelleştirin.
• Hem istemci tarafı hem de sunucu tarafı bileşenlerinde çevirilere erişin.
• Otomatik oluşturulan tiplerle TypeScript desteğini sağlayın, otomatik tamamlama ve hata tespitini iyileştirin.
• Dinamik yerel ayar algılama ve değiştirme gibi gelişmiş özelliklerden yararlanın.

Intlayer; Next.js 12, 13, 14 ve 16 ile uyumludur. Next.js Page Router kullanıyorsanız, bu kılavuza bakabilirsiniz. Yerel ayar yönlendirmesi (Locale routing) SEO, paket boyutu ve performans için faydalıdır. İhtiyacınız yoksa, bu kılavuza bakabilirsiniz. App Router ile Next.js 12, 13, 14 için bu kılavuza bakın.

Next.js Uygulamasında Intlayer Kurulumu Adım Adım Rehber

Adım 1: Bağımlılıkları Yükleyin

Gerekli paketleri npm kullanarak yükleyin:

npm install intlayer next-intlayernpx intlayer init

• intlayer

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

• next-intlayer

  Intlayer'ı Next.js ile entegre eden paket. Next.js uluslararasılaştırması için bağlam sağlayıcıları ve kancalar sunar. Ayrıca, Intlayer'ı Webpack veya Turbopack ile entegre etmek için Next.js eklentisinin yanı sıra kullanıcının tercih ettiği yerel ayarı algılamak, çerezleri yönetmek ve URL yönlendirmesini işlemek için bir proxy içerir.

Adım 2: Projenizi Yapılandırın

İşte yapacağımız nihai yapı:

.├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Intlayer sağlayıcısı için yerel ayar düzeni│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Stil ve küresel sağlayıcılar için kök düzen│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

Yerel ayar yönlendirmesi (locale routing) istemiyorsanız, intlayer basit bir sağlayıcı / kanca olarak kullanılabilir. Daha fazla ayrıntı için bu kılavuza bakın.

Uygulamanızın dillerini yapılandırmak 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
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

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

Adım 3: Intlayer'ı Next.js Yapılandırmanıza Entegre Edin

Next.js kurulumunuzu Intlayer kullanacak şekilde yapılandırın:

import type { NextConfig } from "next";
import { withIntlayer } from "next-intlayer/server";

const nextConfig: NextConfig = {
  /* buraya yapılandırma seçenekleri */
};

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 geliştirme modunda bunları izler. Intlayer ortam değişkenlerini Webpack veya Turbopack ortamlarında tanımlar. Ek olarak, performansı optimize etmek için takma adlar (aliases) sağlar ve sunucu bileşenleriyle uyumluluğu garanti eder.

withIntlayer() fonksiyonu bir promise fonksiyonudur. Build başlamadan önce Intlayer sözlüklerini hazırlamaya olanak tanır. Başka eklentilerle birlikte kullanmak isterseniz, onu await edebilirsiniz. Örnek:

ts

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Senkron olarak kullanmak isterseniz withIntlayerSync() fonksiyonunu kullanabilirsiniz. Örnek:

ts

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Intlayer, komut satırı bayrakları --webpack, --turbo veya --turbopack ile mevcut Next.js sürümünüze bağlı olarak projenizin webpack mi yoksa Turbopack mi kullandığını otomatik olarak algılar.

next>=16 sürümünden itibaren Rspack kullanıyorsanız, Turbopack'i devre dışı bırakarak Intlayer'ı açıkça webpack yapılandırmasını kullanmaya zorlamalısınız:

ts

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

Adım 4: Dinamik Yerel Ayar Rotalarını Tanımlayın

RootLayout içindeki her şeyi kaldırın ve aşağıdaki kodla değiştirin:

import type { PropsWithChildren, FC } from "react";
import "./globals.css";

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  // Çocukları hala `next-themes`, `react-query`, `framer-motion` vb. gibi diğer sağlayıcılarla sarmalayabilirsiniz.
  <>{children}</>
);

export default RootLayout;

RootLayout bileşenini boş bırakmak, <html> etiketine lang ve dir özniteliklerini ayarlamaya olanak tanır.

Dinamik yönlendirmeyi uygulamak için, [locale] dizininizde yeni bir düzen ekleyerek yerel ayar yolunu sağlayın:

import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body className={inter.className}>
        <IntlayerClientProvider locale={locale}>
          {children}
        </IntlayerClientProvider>
      </body>
    </html>
  );
};

export default LocaleLayout;

[locale] yol segmenti, yerel ayarı tanımlamak için kullanılır. Örnek: /en-US/about, en-US'ye ve /fr/about, fr'ye atıfta bulunacaktır.

Bu aşamada şu hatayla karşılaşacaksınız: Error: Missing <html> and <body> tags in the root layout.. Bu beklenen bir durumdur çünkü /app/page.tsx dosyası artık kullanılmıyor ve kaldırılabilir. Bunun yerine, [locale] yol segmenti /app/[locale]/page.tsx sayfasını etkinleştirecektir. Sonuç olarak, sayfalar tarayıcınızda /en, /fr, /es gibi yollar üzerinden erişilebilir olacaktır. Varsayılan yerel ayarı kök sayfa olarak ayarlamak için 7. adımdaki proxy kurulumuna bakın.

Ardından, uygulama Düzeninizde (Layout) generateStaticParams fonksiyonunu uygulayın.

export { generateStaticParams } from "next-intlayer"; // Eklenecek satır

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  /*... Kodun geri kalanı*/
};

export default LocaleLayout;

generateStaticParams, uygulamanızın tüm yerel ayarlar için gerekli sayfaları önceden oluşturmasını sağlayarak çalışma zamanı hesaplamasını azaltır ve kullanıcı deneyimini iyileştirir. Daha fazla ayrıntı için generateStaticParams üzerine Next.js dokümantasyonuna bakın.

Intlayer, sayfaların tüm yerel ayarlar için önceden oluşturulmasını sağlamak amacıyla export const dynamic = 'force-static'; ile çalışır.

Adım 5: İçeriğinizi Bildirin

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

import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        en: "Get started by editing",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} satisfies Dictionary;

export default pageContent;

İçerik bildirimleriniz, contentDir dizinine (varsayılan olarak ./src) dahil edildiği sürece uygulamanızın herhangi bir yerinde tanımlanabilir. Ve içerik bildirimi dosya uzantısıyla eşleşmelidir (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Daha fazla ayrıntı için içerik bildirimi dokümantasyonuna bakın.

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

Uygulamanız genelinde içerik sözlüklerinize erişin:

import type { FC } from "react";
import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type NextPageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const PageContent: FC = () => {
  const content = useIntlayer("page");

  return (
    <>
      <p>{content.getStarted.main}</p>
      <code>{content.getStarted.pageLink}</code>
    </>
  );
};

const Page: NextPageIntlayer = async ({ params }) => {
  const { locale } = await params;

  return (
    <IntlayerServerProvider locale={locale}>
      <PageContent />
      <ServerComponentExample />

      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;

• IntlayerClientProvider, yerel ayarı istemci tarafı bileşenlere sağlamak için kullanılır. Düzen dahil herhangi bir üst bileşene yerleştirilebilir. Ancak, Next.js düzen kodunu sayfalar arasında paylaştığı ve bu da onu daha verimli kıldığı için bir düzene yerleştirilmesi önerilir. IntlayerClientProvider'ı düzende kullanarak, her sayfa için yeniden başlatılmasını önler, performansı artırır ve uygulamanız genelinde tutarlı bir yerelleştirme bağlamı sağlarsınız.

• IntlayerServerProvider, yerel ayarı sunucu tarafı çocuklara sağlamak için kullanılır. Düzende (layout) ayarlanamaz.

  Düzen (layout) ve sayfa ortak bir sunucu bağlamını paylaşamaz çünkü sunucu bağlamı sistemi her istek için veri deposuna (React'in cache mekanizması aracılığıyla) dayanır ve her "bağlamın" uygulamanın farklı segmentleri için yeniden oluşturulmasına neden olur. Sağlayıcıyı paylaşılan bir düzene yerleştirmek bu izolasyonu bozacak ve sunucu bağlamı değerlerinin sunucu bileşenlerinize doğru şekilde yayılmasını engelleyecektir.

"use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

export const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // İlgili içerik bildirimini oluşturun

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

export const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // İlgili içerik bildirimini oluşturun

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

İçeriğinizi alt, title, href, aria-label vb. gibi bir string özniteliğinde kullanmak istiyorsanız, fonksiyonun değerini çağırmalısınız, örneğin:

html

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

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

Eğer uygulamanız zaten mevcutsa, binlerce bileşeni bir saniye içinde dönüştürmek için Intlayer Compiler'ı extract komutu ile birlikte kullanabilirsiniz.

(İsteğe Bağlı) Adım 7: Yerel Ayar Algılama İçin Proxy Yapılandırın

Kullanıcının tercih ettiği yerel ayarı algılamak için proxy'yi ayarlayın:

export { intlayerProxy as proxy } from "next-intlayer/proxy";

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

intlayerProxy, kullanıcının tercih ettiği yerel ayarı algılamak ve onları yapılandırmada belirtilen uygun URL'ye yönlendirmek için kullanılır. Ek olarak, kullanıcının tercih ettiği yerel ayarın bir çerezde saklanmasını sağlar.

Birden fazla proxy'yi bir zincirleme olarak bağlamanız gerekiyorsa (örneğin, kimlik doğrulama veya özel proxy'lerle birlikte intlayerProxy), Intlayer artık multipleProxies adında bir yardımcı sunuyor.

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

(İ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 istediğiniz durumda, Next.js tarafından sağlanan generateMetadata fonksiyonunu kullanabilirsiniz. İçinde, meta verilerinizi çevirmek için getIntlayer fonksiyonundan içeriği alabilirsiniz.

import { type Dictionary, t } from "intlayer";
import { 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 { getIntlayer, getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;

  const metadata = getIntlayer("page-metadata", locale);

  /**
   * Her bir 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("/");
  const localizedUrl =
    multilingualUrls[locale as keyof typeof multilingualUrls];

  return {
    ...metadata,
    alternates: {
      canonical: localizedUrl,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: localizedUrl,
    },
  };
};

// ... Kodun geri kalanı

next-intlayer'dan içe aktarılan getIntlayer fonksiyonunun içeriğinizi bir IntlayerNode içine sarılmış olarak döndürdüğünü ve görsel editörle entegrasyona olanak tanıdığını unutmayın. Buna karşılık, intlayer'dan içe aktarılan getIntlayer fonksiyonu, içeriğinizi ek özellikler olmadan doğrudan döndürür.

Alternatif olarak, meta verilerinizi bildirmek için getTranslation fonksiyonunu kullanabilirsiniz. Ancak, meta verilerinizin çevirisini otomatikleştirmek ve bir noktada içeriği dışsallaştırmak için içerik bildirim dosyalarını kullanmanız önerilir.

import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  return {
    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",
    }),
  };
};

// ... Kodun geri kalanı

Meta veri optimizasyonu hakkında daha fazla bilgiyi resmi Next.js dokümantasyonunda bulabilirsiniz.

(İsteğe Bağlı) Adım 9: sitemap.xml ve robots.txt Uluslararasılaştırılması

sitemap.xml ve robots.txt dosyalarınızı uluslararasılaştırmak için Intlayer tarafından sağlanan getMultilingualUrls fonksiyonunu kullanabilirsiniz. Bu fonksiyon, sitemap'iniz için çok dilli URL'ler oluşturmanıza olanak tanır.

import { getMultilingualUrls } from "intlayer";
import type { MetadataRoute } from "next";

const sitemap = (): MetadataRoute.Sitemap => [
  {
    url: "https://example.com",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com"),
        "x-default": "https://example.com",
      },
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/login"),
        "x-default": "https://example.com/login",
      },
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/register"),
        "x-default": "https://example.com/register",
      },
    },
  },
];

export default sitemap;

import type { MetadataRoute } from "next";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]),
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;

Sitemap optimizasyonu hakkında daha fazla bilgiyi resmi Next.js dokümantasyonunda bulabilirsiniz. robots.txt optimizasyonu hakkında daha fazla bilgiyi resmi Next.js dokümantasyonunda bulabilirsiniz.

(İsteğe Bağlı) Adım 10: İçeriğinizin Dilini Değiştirme

Next.js'te içeriğinizin dilini değiştirmek için önerilen yöntem, kullanıcıları uygun yerelleştirilmiş sayfaya yönlendirmek için Link bileşenini kullanmaktır. Link bileşeni sayfanın önceden yüklenmesini (prefetching) sağlar, bu da tam bir sayfa yenilenmesini önlemeye yardımcı olur.

"use client";

import type { FC } from "react";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import Link from "next/link";

export const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales, setLocale } =
    useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
            replace // Tarayıcıdaki "geri" düğmesinin önceki sayfaya yönlendirmesini sağlar
          >
            <span>
              {/* Yerel ayar - örn. FR */}
              {localeItem}
            </span>
            <span>
              {/* Kendi yerel ayarında dil adı - örn. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Mevcut yerel ayarda dil adı - örn. mevcut yerel ayar Locales.SPANISH olduğunda Francés */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* İngilizce dil adı - örn. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        ))}
      </div>
    </div>
  );
};

Alternatif bir yol da useLocale kancasıyla sağlanan setLocale fonksiyonunu kullanmaktır. Bu fonksiyon sayfanın önceden yüklenmesine (prefetching) izin vermez. Daha fazla ayrıntı için useLocale kancası dokümantasyonuna bakın.

Ayrıca, yerel ayar değiştiğinde özel bir fonksiyonu tetiklemek için onLocaleChange seçeneğinde bir fonksiyon ayarlayabilirsiniz.

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

Dokümantasyon referansları:

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

(İsteğe Bağlı) Adım 11: Yerelleştirilmiş Bir Link Bileşeni Oluşturma

Uygulamanızın navigasyonunun mevcut yerel ayara saygı göstermesini sağlamak için özel bir Link bileşeni oluşturabilirsiniz. Bu bileşen, dahili URL'lerin önüne otomatik olarak geçerli dil kodunu ekler. Örneğin, Fransızca konuşan bir kullanıcı "Hakkında" sayfasının bağlantısına tıkladığında, /about yerine /fr/about sayfasına yönlendirilir.

Bu davranış birkaç nedenden dolayı yararlıdır:

• SEO ve Kullanıcı Deneyimi: Yerelleştirilmiş URL'ler, arama motorlarının dile özgü sayfaları doğru şekilde indekslemesine yardımcı olur ve kullanıcılara tercih ettikleri dilde içerik sunar.
• Tutarlılık: Uygulamanız boyunca yerelleştirilmiş bir bağlantı kullanarak, gezinmenin mevcut yerel ayar içinde kalmasını garanti eder, beklenmedik dil değişikliklerini önlersiniz.
• Bakım Kolaylığı: Yerelleştirme mantığını tek bir bileşende merkezileştirmek, URL yönetimini basitleştirir ve uygulamanız büyüdükçe kod tabanınızın bakımını ve genişletilmesini kolaylaştırır.

Aşağıda TypeScript ile yerelleştirilmiş bir Link bileşeninin uygulaması yer almaktadır:

"use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import type { PropsWithChildren, FC } from "react";

/**
 * Verilen URL'nin harici olup olmadığını kontrol eden yardımcı fonksiyon.
 * URL http:// veya https:// ile başlıyorsa harici kabul edilir.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * Mevcut yerel ayara göre href özniteliğini uyarlayan özel bir Link bileşeni.
 * Dahili bağlantılar için, URL'nin önüne yerel ayarı eklemek için `getLocalizedUrl` kullanılır (örn. /fr/about).
 * Bu, navigasyonun aynı yerel ayar bağlamında kalmasını sağlar.
 */
export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
  href,
  children,
  ...props
}) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // Bağlantı dahiliyse 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} {...props}>
      {children}
    </NextLink>
  );
};

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 yerelleştirilmeye ihtiyaç duymadığı için değişmeden bırakılır.

• 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 için (yani harici olmayan), getLocalizedUrl kullanılarak URL'nin önüne otomatik olarak geçerli yerel ayar eklenir. Bu, kullanıcınız Fransızca ise /about olarak iletilen href özniteliğinin /fr/about olarak dönüştürüleceği anlamına gelir.

• Bağlantıyı Döndürme:
  Bileşen, yerelleştirilmiş URL'ye sahip bir <a> elemanı döndürerek navigasyonun yerel ayarla tutarlı olmasını sağlar.

Bu Link bileşenini uygulamanız genelinde entegre ederek, tutarlı ve dile duyarlı bir kullanıcı deneyimi sağlarken, aynı zamanda iyileştirilmiş SEO ve kullanılabilirlikten faydalanırsınız.

(İsteğe Bağlı) Adım 12: Server Action'larda Mevcut Yerel Ayarı Alma

Bir Sunucu Eylemi (Server Action) içinde aktif yerel ayara ihtiyacınız varsa (örneğin, e-postaları yerelleştirmek veya yerel ayara duyarlı mantık yürütmek için), next-intlayer/server üzerinden getLocale fonksiyonunu çağırın:

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Yerel ayarla bir şeyler yapın};

getLocale fonksiyonu, kullanıcının yerel ayarını belirlemek için kademeli bir strateji izler:

1. Önce, proxy tarafından ayarlanmış olabilecek bir yerel ayar değeri için istek başlıklarını (headers) kontrol eder.
2. Başlıklarda yerel ayar bulunamazsa, çerezlerde (cookies) saklanan bir yerel ayara bakar.
3. Çerez bulunamazsa, tarayıcı ayarlarından kullanıcının tercih ettiği dili algılamaya çalışır.
4. Son çare olarak, uygulamanın yapılandırılmış varsayılan yerel ayarına geri döner.

Bu, mevcut bağlama göre en uygun yerel ayarın seçilmesini sağlar.

(İsteğe Bağlı) Adım 13: 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, makroları kullanarak useIntlayer çağrılarını akıllıca değiştiren isteğe bağlı bir SWC eklentisi sunar. Bu, sözlüklerin yalnızca onları gerçekten kullanan sayfaların paketlerine dahil edilmesini sağlar.

Bu optimizasyonu etkinleştirmek için @intlayer/swc paketini yükleyin. Yüklendikten sonra next-intlayer eklentiyi otomatik olarak algılayacak ve kullanacaktır:

npm install @intlayer/swc --save-dev

Not: Bu optimizasyon yalnızca Next.js 13 ve üzeri sürümlerde mevcuttur.

Not: Bu paket varsayılan olarak yüklü değildir çünkü SWC eklentileri Next.js'te hala deneysel aşamadadır. Gelecekte değişebilir.

Not: dictionary yapılandırmasında seçeneği importMode: 'dynamic' veya importMode: 'fetch' olarak ayarlarsanız, Suspense'e dayalı olacaktır, bu nedenle useIntlayer çağrılarınızı bir Suspense sınırı (boundary) içine sarmalamanız gerekecektir. Bu, useIntlayer'ı doğrudan Sayfa / Düzen bileşeninizin en üst düzeyinde kullanamayacağınız anlamına gelir.

Turbopack'te Sözlük Değişikliklerini İzleyin

Next.js 16 uygulamanızı geliştirme sunucusu olarak Turbopack (next dev komutuyla) kullanırken, sözlük değişiklikleri varsayılan olarak otomatik olarak algılanmayacaktır.

Bu sınırlama, Turbopack'in içerik dosyalarınızdaki değişiklikleri izlemek için webpack eklentilerini paralel olarak çalıştıramamasından kaynaklanmaktadır. Bunu aşmak için hem geliştirme sunucusunu hem de Intlayer build izleyicisini eşzamanlı olarak çalıştırmak üzere intlayer watch komutunu kullanmanız gerekecektir.

{  // ... Mevcut package.json yapılandırmalarınız  "scripts": {    // ... Mevcut scripts yapılandırmalarınız    "dev": "intlayer watch --with 'next dev'",  },}

next-intlayer@<=6.x.x kullanıyorsanız, Next.js 16 uygulamasının Turbopack ile doğru çalışması için --turbopack bayrağını korumanız gerekir. Bu sınırlamadan kaçınmak için next-intlayer@>=7.x.x kullanmanızı öneririz.

TypeScript Yapılandırması

Intlayer, TypeScript'in avantajlarından yararlanmak ve kod tabanınızı daha güçlü hale getirmek için modül genişletme (module augmentation) kullanır.

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

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

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaların yoksayılması önerilir. Bu, onları Git deponuza göndermenizi engeller.

Bunu yapmak için .gitignore dosyanıza aşağıdaki talimatları ekleyebilirsiniz:

# Intlayer tarafından oluşturulan dosyaları yoksay.intlayer

VS Code Uzantısı

Intlayer ile geliştirme deneyiminizi iyileştirmek için resmi Intlayer VS Code Uzantısını yükleyebilirsiniz.

VS Code Marketplace'ten yükleyin

Bu uzantı şunları sağlar:

• Çeviri anahtarları için otomatik tamamlama.
• Eksik çeviriler için gerçek zamanlı hata tespiti.
• Ç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ğına ilişkin daha fazla ayrıntı için Intlayer VS Code Uzantısı dokümantasyonuna bakın.

(İsteğe bağlı) Adım 14 : Bileşenlerinizin içeriğini çıkarın

Mevcut bir kod tabanınız varsa, binlerce dosyayı dönüştürmek zaman alıcı olabilir.

Bu süreci kolaylaştırmak için Intlayer, bileşenlerinizi dönüştürmek ve içeriği çıkarmak için bir derleyici / çıkarıcı sunar.

Kurulum için intlayer.config.ts dosyanıza bir compiler bölümü ekleyebilirsiniz:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Yapılandırmanızın geri kalanı
  compiler: {
    /**
     * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.
     */
    enabled: true,

    /**
     * Çıktı dosyalarının yolunu tanımlar
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Bileşenlerin dönüştürüldükten sonra kaydedilip kaydedilmeyeceğini belirtir. Bu sayede derleyici, uygulamayı dönüştürmek için yalnızca bir kez çalıştırılabilir ve ardından kaldırılabilir.
     */
    saveComponents: false,

    /**
     * Sözlük anahtarı öneki
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Bileşenlerden içeriği sözlüklere çıkarın   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # Veya npm run dev

Daha İleriye Gidin

Daha ileri gitmek için görsel editörü uygulayabilir veya CMS kullanarak içeriğinizi dışsallaştırabilirsiniz.