Internationalization (i18n) Routing

Examples

Next.js, v10.0.0 adresinden bu yana uluslararasılaştırılmış(i18n) yönlendirme için yerleşik desteğe sahiptir. Yerel ayarların, varsayılan yerel ayarın ve etki alanına özgü yerel ayarların bir listesini sağlayabilirsiniz ve Next.js yönlendirmeyi otomatik olarak gerçekleştirecektir.

i18n yönlendirme desteği şu anda aşağıdaki gibi mevcut i18n kütüphane çözümlerini tamamlamak için tasarlanmıştır react-intl, react-i18next, lingui, rosetta, next-intl, next-translate, next-multilingual, tolgeeve diğerlerini rotaları ve yerel ayar ayrıştırmasını kolaylaştırarak.

Getting started

Başlamak için i18n yapılandırmasını next.config.js dosyanıza ekleyin.

Yereller, yerelleri tanımlamak için standartlaştırılmış bir format olan UTS Yerel Tanımlayıcıları'dur.

Genel olarak bir Yerel Ayar Tanımlayıcısı, bir tire ile ayrılmış bir dil, bölge ve komut dosyasından oluşur: language-region-script. Bölge ve komut dosyası isteğe bağlıdır. Bir örnek:

Kullanıcı yerel ayarı nl-BE ise ve yapılandırmanızda listelenmemişse, varsa nl adresine, yoksa varsayılan yerel ayara yönlendirilirler. Bir ülkenin tüm bölgelerini desteklemeyi planlamıyorsanız, bu nedenle geri dönüş olarak hareket edecek ülke yerel ayarlarını dahil etmek iyi bir uygulamadır.

next.config.js
module.exports = {
  i18n: {
    // These are all the locales you want to support in
    // your application
    locales: ['en-US', 'fr', 'nl-NL'],
    // This is the default locale you want to be used when visiting
    // a non-locale prefixed path e.g. `/hello`
    defaultLocale: 'en-US',
    // This is a list of locale domains and the default locale they
    // should handle (these are only required when setting up domain routing)
    // Note: subdomains must be included in the domain value to be matched e.g. "fr.example.com".
    domains: [
      {
        domain: 'example.com',
        defaultLocale: 'en-US',
      },
      {
        domain: 'example.nl',
        defaultLocale: 'nl-NL',
      },
      {
        domain: 'example.fr',
        defaultLocale: 'fr',
        // an optional http field can also be used to test
        // locale domains locally with http instead of https
        http: true,
      },
    ],
  },
}

Locale Strategies

İki yerel ayar işleme stratejisi vardır: Alt yol Yönlendirme ve Etki Alanı Yönlendirme.

Sub-path Routing

Alt yol Yönlendirme, yerel ayarı url yoluna yerleştirir.

next.config.js
module.exports = {
  i18n: {
    locales: ['en-US', 'fr', 'nl-NL'],
    defaultLocale: 'en-US',
  },
}

Yukarıdaki yapılandırma ile en-US, fr, ve nl-NL yönlendirilmek için kullanılabilir olacaktır ve en-US varsayılan yerel ayar olacaktır. Eğer bir pages/blog.js adresiniz varsa aşağıdaki URL'ler kullanılabilir olacaktır:

Varsayılan yerel ayarın bir öneki yoktur.

Domain Routing

Etki alanı yönlendirmesini kullanarak yerel ayarları farklı etki alanlarından sunulacak şekilde yapılandırabilirsiniz:

next.config.js
module.exports = {
  i18n: {
    locales: ['en-US', 'fr', 'nl-NL', 'nl-BE'],
    defaultLocale: 'en-US',
 
    domains: [
      {
        // Note: subdomains must be included in the domain value to be matched
        // e.g. www.example.com should be used if that is the expected hostname
        domain: 'example.com',
        defaultLocale: 'en-US',
      },
      {
        domain: 'example.fr',
        defaultLocale: 'fr',
      },
      {
        domain: 'example.nl',
        defaultLocale: 'nl-NL',
        // specify other locales that should be redirected
        // to this domain
        locales: ['nl-BE'],
      },
    ],
  },
}

Örneğin pages/blog.js adresiniz varsa aşağıdaki URL'ler kullanılabilir olacaktır:

Automatic Locale Detection

Bir kullanıcı uygulama kök dizinini ziyaret ettiğinde (genellikle /), Next.js kullanıcının hangi yerel ayarı tercih ettiğini otomatik olarak algılamaya çalışacaktır. Accept-Language başlığı ve geçerli etki alanı.

Varsayılan yerel ayar dışında bir yerel ayar tespit edilirse, kullanıcı ikisinden birine yönlendirilir:

Etki Alanı Yönlendirmesi kullanılırken, Accept-Language üstbilgisine sahip bir kullanıcı fr;q=0.9 adresinden example.com adresini ziyaret ederse, bu etki alanı varsayılan olarak fr yerel ayarını işlediğinden example.fr adresine yönlendirilecektir.

Alt Yol Yönlendirmesi kullanıldığında, kullanıcı /fr adresine yönlendirilir.

Prefixing the Default Locale

Next.js 12 ve Middleware ile, geçici çözümüyle varsayılan yerel ayara bir önek ekleyebiliriz.

Örneğin, burada birkaç dil için destek içeren bir next.config.js dosyası bulunmaktadır. "default" yerel ayarının kasıtlı olarak eklendiğine dikkat edin.

next.config.js
module.exports = {
  i18n: {
    locales: ['default', 'en', 'de', 'fr'],
    defaultLocale: 'default',
    localeDetection: false,
  },
  trailingSlash: true,
}

Ardından, özel yönlendirme kuralları eklemek için Middleware 'i kullanabiliriz:

middleware.ts
import { NextRequest, NextResponse } from 'next/server'
 
const PUBLIC_FILE = /\.(.*)$/
 
export async function middleware(req: NextRequest) {
  if (
    req.nextUrl.pathname.startsWith('/_next') ||
    req.nextUrl.pathname.includes('/api/') ||
    PUBLIC_FILE.test(req.nextUrl.pathname)
  ) {
    return
  }
 
  if (req.nextUrl.locale === 'default') {
    const locale = req.cookies.get('NEXT_LOCALE')?.value || 'en'
 
    return NextResponse.redirect(
      new URL(`/${locale}${req.nextUrl.pathname}${req.nextUrl.search}`, req.url)
    )
  }
}

Bu Orta Yazılım, API Rotalarına ve yazı tipleri veya resimler gibi genel dosyalara varsayılan öneki eklemeyi atlar. Varsayılan yerel ayara bir istek yapılırsa, önekimize yönlendiririz /en.

Disabling Automatic Locale Detection

Otomatik yerel ayar algılama şu şekilde devre dışı bırakılabilir:

next.config.js
module.exports = {
  i18n: {
    localeDetection: false,
  },
}

localeDetection false olarak ayarlandığında Next.js artık kullanıcının tercih ettiği yerel ayara göre otomatik olarak yönlendirme yapmayacak ve yalnızca yukarıda açıklandığı gibi yerel ayara dayalı etki alanından veya yerel ayar yolundan algılanan yerel ayar bilgilerini sağlayacaktır.

Accessing the locale information

Yerel ayar bilgilerine Next.js yönlendiricisi üzerinden erişebilirsiniz. Örneğin, şu yönlendiriciyi kullanarak useRouter() kanca aşağıdaki özellikler mevcuttur:

Sayfaları getStaticProps veya getServerSideProps ile önceden oluştururken, yerel ayar bilgileri işleve sağlanan bağlamda sağlanır.

getStaticPaths adresinden yararlanırken, yapılandırılmış yerel ayarlar locales altındaki işlevin bağlam parametresinde ve yapılandırılmış defaultLocale defaultLocale altında sağlanır.

Transition between locales

Yerel ayarlar arasında geçiş yapmak için next/link veya next/router adreslerini kullanabilirsiniz.

next/link için, o anda etkin olandan farklı bir yerel ayara geçiş yapmak için bir locale prop sağlanabilir. Herhangi bir locale prop'u sağlanmazsa, istemci geçişleri sırasında o anda etkin olan locale kullanılır. Örneğin:

import Link from 'next/link'
 
export default function IndexPage(props) {
  return (
    <Link href="/another" locale="fr">
      To /fr/another
    </Link>
  )
}

next/router yöntemlerini doğrudan kullanırken, geçiş seçenekleri aracılığıyla kullanılması gereken locale adresini belirtebilirsiniz. Örneğin:

import { useRouter } from 'next/router'
 
export default function IndexPage(props) {
  const router = useRouter()
 
  return (
    <div
      onClick={() => {
        router.push('/another', '/another', { locale: 'fr' })
      }}
    >
      to /fr/another
    </div>
  )
}

Dinamik rota sorgu değerleri veya gizli href sorgu değerleri gibi tüm yönlendirme bilgilerini korurken yalnızca locale adresini değiştirmeyi işlemek için href parametresini bir nesne olarak sağlayabileceğinizi unutmayın:

import { useRouter } from 'next/router'
const router = useRouter()
const { pathname, asPath, query } = router
// change just the locale and maintain all other route information including href's query
router.push({ pathname, query }, asPath, { locale: nextLocale })

router.push nesne yapısı hakkında daha fazla bilgi için buraya bakın.

Zaten yerel ayarı içeren bir href adresiniz varsa, yerel ayar önekinin otomatik olarak işlenmesini devre dışı bırakabilirsiniz:

import Link from 'next/link'
 
export default function IndexPage(props) {
  return (
    <Link href="/fr/another" locale={false}>
      To /fr/another
    </Link>
  )
}

Next.js, accept-language başlığının bir NEXT_LOCALE=the-locale çerezi ile geçersiz kılınmasını destekler. Bu çerez bir dil değiştirici kullanılarak ayarlanabilir ve daha sonra bir kullanıcı siteye geri döndüğünde, / adresinden doğru yerel konuma yönlendirirken çerezde belirtilen yerel ayardan yararlanacaktır.

Örneğin, bir kullanıcı accept-language başlığında fr yerel ayarını tercih ederse ancak NEXT_LOCALE=en çerezi / adresini ziyaret ederken en yerel ayarını ayarlarsa, çerez kaldırılana veya süresi dolana kadar kullanıcı en yerel ayar konumuna yönlendirilecektir.

Search Engine Optimization

Next.js kullanıcının hangi dili ziyaret ettiğini bildiği için <html> etiketine otomatik olarak lang niteliğini ekleyecektir.

Next.js bir sayfanın varyantları hakkında bilgi sahibi değildir, bu nedenle hreflang meta etiketlerini eklemek size kalmıştır. next/head. Google Webmasters belgelerinde hreflang hakkında daha fazla bilgi edinebilirsiniz .

How does this work with Static Generation?

Uluslararasılaştırılmış Yönlendirme'nin aşağıdakilerle entegre olmadığını unutmayın output: 'export' Next.js yönlendirme katmanından yararlanmadığı için. output: 'export' kullanmayan hibrit Next.js uygulamaları tamamen desteklenmektedir.

Dynamic Routes and getStaticProps Pages

Dinamik Rotalar ile getStaticProps adresini kullanan sayfalar için, önceden oluşturulmak istenen sayfanın tüm yerel ayar varyantlarının şu adresten döndürülmesi gerekir getStaticPaths. paths için döndürülen params nesnesinin yanı sıra, hangi yerel ayarı işlemek istediğinizi belirten bir locale alanı da döndürebilirsiniz. Örneğin:

pages/blog/[slug].js
export const getStaticPaths = ({ locales }) => {
  return {
    paths: [
      // if no `locale` is provided only the defaultLocale will be generated
      { params: { slug: 'post-1' }, locale: 'en-US' },
      { params: { slug: 'post-1' }, locale: 'fr' },
    ],
    fallback: true,
  }
}

Otomatik Olarak Statik Olarak Optimize Edilmiş ve dinamik olmayan getStaticProps sayfaları için, her yerel ayar için sayfanın bir sürümü oluşturulacaktır. Bunu dikkate almak önemlidir çünkü getStaticProps içinde kaç yerel ayar yapılandırıldığına bağlı olarak derleme sürelerini artırabilir.

Örneğin, getStaticProps adresini kullanarak 10 dinamik olmayan sayfa ile yapılandırılmış 50 yerel ayarınız varsa, bu getStaticProps adresinin 500 kez çağrılacağı anlamına gelir. Her derleme sırasında 10 sayfanın 50 sürümü oluşturulacaktır.

getStaticProps ile dinamik sayfaların derleme süresini azaltmak için fallback modunu kullanın. Bu, derleme sırasında ön oluşturma için getStaticPaths adresinden yalnızca en popüler yolları ve yerel ayarları döndürmenize olanak tanır. Ardından, Next.js kalan sayfaları çalışma zamanında talep edildikçe oluşturacaktır.

Automatically Statically Optimized Pages

Otomatik olarak statik olarak optimize edilen sayfalar için, her yerel ayar için sayfanın bir sürümü oluşturulacaktır.

Non-dynamic getStaticProps Pages

Dinamik olmayan getStaticProps sayfaları için, yukarıdaki gibi her yerel ayar için bir sürüm oluşturulur. getStaticProps, oluşturulmakta olan her locale ile birlikte çağrılır. Belirli bir yerel ayarın önceden oluşturulmasını istemiyorsanız, getStaticProps adresinden notFound: true adresini döndürebilirsiniz ve sayfanın bu çeşidi oluşturulmayacaktır.

export async function getStaticProps({ locale }) {
  // Call an external API endpoint to get posts.
  // You can use any data fetching library
  const res = await fetch(`https://.../posts?locale=${locale}`)
  const posts = await res.json()
 
  if (posts.length === 0) {
    return {
      notFound: true,
    }
  }
 
  // By returning { props: posts }, the Blog component
  // will receive `posts` as a prop at build time
  return {
    props: {
      posts,
    },
  }
}

Limits for the i18n config

Bilmekte fayda var: Bu sınırlar başlangıçta derleme sırasında olası performans sorunlarını önlemek için eklenmiştir. Next.js 12'de Middleware kullanarak özel yönlendirme ile bu sınırları aşabilirsiniz.