Intlayer ile Next.js 14 and App Router çevirin | Uluslararasılaştırma (i18n)

Bu kılavuz, Next.js 14 uygulamanızda Intlayer'ı nasıl kuracağınızı ve kullanacağınızı adım adım açıklar. Intlayer, Next.js 14 ile sorunsuz bir şekilde entegre olur ve çok dilli içerik yönetimi sağlar.

Ön Koşullar

Bu kılavuzu takip etmek için aşağıdaki araçlara ihtiyacınız olacak:

• Node.js 18 veya üzeri
• npm, pnpm veya yarn paket yöneticisi
• Next.js 14 projesi

1. 1

   Intlayer Paketlerini Kurma

   İlk olarak, Intlayer paketlerini projenize kurun:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install next-intlayer intlayer --savenpx intlayer init

2. 2

   Intlayer Yapılandırma Dosyası Oluşturma

   Here is the final structure that we will make:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   .├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── middleware.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

   If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

   Proje kök dizininizde intlayer.config.ts dosyasını oluşturun:

   intlayer.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { Locales } from "intlayer";
   import { type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         Locales.TURKISH,
       ],
       defaultLocale: Locales.ENGLISH,
     },
     content: {
       // İçerik dosyalarınızın bulunduğu dizin
       fileExtensions: [".content.ts", ".content.js", ".content.json"],
       baseDir: "./src",
       contentDirName: "content",
       // İçerik dosyalarınızın türlerini belirtin
       types: {
         filePath: "./types/intlayer.d.ts",
         moduleAugmentation: true,
       },
     },
   };
   
   export default config;

3. 3

   Next.js Yapılandırmasını Güncelleme

   Next.js yapılandırma dosyanızı Intlayer ile uyumlu hale getirin:

4. 4

   İçerik Bildirimi

   İçerik dosyalarınızı oluşturun. Bu dosyalar, uygulamanızdaki çok dilli içeriği tanımlar.

   src/content/home.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { t } from "intlayer";
   import { type ILocaleContent } from "intlayer";
   
   const homeContent = {
     title: t({
       en: "Welcome to My App",
       fr: "Bienvenue dans mon application",
       es: "Bienvenido a mi aplicación",
       tr: "Uygulamama Hoş Geldiniz",
     }),
     description: t({
       en: "This is a sample Next.js application with Intlayer",
       fr: "Ceci est un exemple d'application Next.js avec Intlayer",
       es: "Esta es una aplicación de ejemplo de Next.js con Intlayer",
       tr: "Bu, Intlayer ile örnek bir Next.js uygulamasıdır",
     }),
   } satisfies ILocaleContent;
   
   export default homeContent;

   src/content/home.content.json

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   {  "title": {    "en": "Welcome to My App",    "fr": "Bienvenue dans mon application",    "es": "Bienvenido a mi aplicación",    "tr": "Uygulamama Hoş Geldiniz"  },  "description": {    "en": "This is a sample Next.js application with Intlayer",    "fr": "Ceci est un exemple d'application Next.js avec Intlayer",    "es": "Esta es una aplicación de ejemplo de Next.js con Intlayer",    "tr": "Bu, Intlayer ile örnek bir Next.js uygulamasıdır"  }}

5. 5

   İçerik Kullanımı

   İçeriğinizi bileşenlerinizde kullanın:

   src/app/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { useIntlayer } from "next-intlayer";
   import { Locales } from "intlayer";
   
   export default function HomePage() {
     const content = useIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
       </div>
     );
   }

6. 6

   Middleware Kurulumu

   Next.js 14'te çok dilli yönlendirme için middleware kurun:

   src/middleware.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { createMiddleware } from "next-intlayer/middleware";
   import { type NextRequest } from "next/server";
   
   export default createMiddleware({
     // Alternatif olarak, middleware seçeneklerini özelleştirebilirsiniz
     // locales: ['en', 'fr', 'es'],
     // defaultLocale: 'en',
   });
   
   export const config = {
     matcher: ["/((?!api|_next|_vercel|.*\\..*).*)"],
   };

7. 7

   Düzen Dosyası (Layout)

   Kök düzen dosyanızı çok dilli hale getirin:

   src/app/layout.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import {} from "next-intlayer";
   import { getHTMLTextDir } from "intlayer";
   import { getLocaleName } from "intlayer";
   import { Inter } from "next/font/google";
   import { type Metadata } from "next/types";
   import { getIntlayer } from "next-intlayer/server";
   import { type Locales } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   export const generateMetadata = (params: {
     params: { locale: Locales };
   }): Metadata => {
     const { locale } = params.params;
     const t = getIntlayer(locale);
   
     return {
       title: t({
         en: "My App",
         fr: "Mon Application",
         es: "Mi Aplicación",
         tr: "Uygulamam",
       }),
       description: t({
         en: "This is my Next.js app with Intlayer",
         fr: "Ceci est mon application Next.js avec Intlayer",
         es: "Esta es mi aplicación Next.js con Intlayer",
         tr: "Bu, Intlayer ile Next.js uygulamamdır",
       }),
     };
   };
   
   export default function RootLayout({
     children,
     params,
   }: {
     children: React.ReactNode;
     params: { locale: Locales };
   }) {
     const { locale } = params;
     const localeName = getLocaleName(locale);
     const textDirection = getHTMLTextDir(locale);
   
     return (
       <html lang={locale} dir={textDirection}>
         <body className={inter.className}>
           <header>
             <h1>{localeName}</h1>
           </header>
           {children}
         </body>
       </html>
     );
   }

8. 8

   Sayfa Yönlendirme

   Sayfa yönlendirmelerini çok dilli hale getirin:

   src/app/[locale]/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { useIntlayer } from "next-intlayer";
   import { Locales } from "intlayer";
   
   export default function HomePage() {
     const content = useIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
       </div>
     );
   }

9. 9

   Meta Verilerin Uluslararasılaştırılması

   Sayfa meta verilerini uluslararasılaştırın:

   src/app/[locale]/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { getIntlayer } from "next-intlayer/server";
   import { type Locales } from "intlayer";
   import { type Metadata } from "next/types";
   
   export const generateMetadata = (params: {
     params: { locale: Locales };
   }): Metadata => {
     const { locale } = params.params;
     const t = getIntlayer(locale);
   
     return {
       title: t({
         en: "Home Page",
         fr: "Page d'accueil",
         es: "Página de inicio",
         tr: "Ana Sayfa",
       }),
       description: t({
         en: "Welcome to the home page",
         fr: "Bienvenue sur la page d'accueil",
         es: "Bienvenido a la página de inicio",
         tr: "Ana sayfaya hoş geldiniz",
       }),
     };
   };
   
   export default function HomePage() {
     const content = getIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
       </div>
     );
   }

10. 10

    Site Haritası ve Robots.txt Kurulumu

    Site haritanızı ve robots.txt dosyanızı çok dilli hale getirin:

    src/app/[locale]/sitemap.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { getLocalizedUrl } from "intlayer";
    import { Locales } from "intlayer";
    import { type MetadataRoute } from "next";
    
    export default function sitemap(): MetadataRoute.Sitemap {
      const locales = [
        Locales.ENGLISH,
        Locales.FRENCH,
        Locales.SPANISH,
        Locales.TURKISH,
      ];
    
      return [
        {
          url: getLocalizedUrl("/", Locales.ENGLISH),
          lastModified: new Date(),
          changeFrequency: "yearly",
          priority: 1,
          alternates: {
            languages: locales.reduce(
              (acc, locale) => ({
                ...acc,
                [locale]: getLocalizedUrl("/", locale),
              }),
              {}
            ),
          },
        },
      ];
    }

    src/app/[locale]/robots.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { getLocalizedUrl } from "intlayer";
    import { Locales } from "intlayer";
    import { type MetadataRoute } from "next";
    
    export default function robots(): MetadataRoute.Robots {
      return {
        rules: {
          userAgent: "*",
          allow: "/",
          disallow: "/private/",
        },
        sitemap: getLocalizedUrl("/sitemap.xml", Locales.ENGLISH),
      };
    }

11. 11

    Yerel Anahtarlayıcı Bileşeni Oluşturma

    Uygulamanızın mevcut yerel ayarı saygı göstermesini sağlamak için, bir yerel anahtarlayıcı 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:

    src/components/LocaleSwitcher.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    "use client";
    
    import { useRouter } from "next/navigation";
    import { useLocale } from "next-intlayer";
    import { getLocalizedUrl } from "intlayer";
    import { Locales } from "intlayer";
    
    const LocaleSwitcher = () => {
      const router = useRouter();
      const { locale } = useLocale();
    
      const handleLocaleChange = (newLocale: Locales) => {
        const pathWithoutLocale = window.location.pathname.replace(
          /^\/[a-z]{2}/,
          ""
        );
        router.push(getLocalizedUrl(pathWithoutLocale, newLocale));
      };
    
      return (
        <div>
          <h2>Dil Seçin</h2>
          <div>
            {Object.values(Locales).map((localeItem) => (
              <button
                key={localeItem}
                onClick={() => handleLocaleChange(localeItem)}
                disabled={locale === localeItem}
              >
                {localeItem.toUpperCase()}
              </button>
            ))}
          </div>
        </div>
      );
    };
    
    export default LocaleSwitcher;

    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.

    src/components/LocaleSwitcher.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    "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>);

    Dokümantasyon referansları:

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

12. 12

    Yerelleştirilmiş Bağlantı Bileşeni Oluşturma

    İsteğe bağlı

    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:

    src/components/Link.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

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

13. 13

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

14. 14

    bundle boyutunuzu Optimize Edin

    İsteğe bağlı

    next-intlayer kullanırken, sözlükler varsayılan olarak her sayfa için pakete dahil edilir. bundle 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:

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    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

Intlayer tarafından oluşturulan dosyaları yok saymanız önerilir. Bu, onları Git deposuna göndermemenizi sağlar.

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

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

Daha Fazla Bilgi Edinin

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