Yaklaşan Intlayer sürümleri hakkında bildirim alın
    Oluşturma:2025-09-07Son güncelleme:2025-09-07

    Intlayer ile React Create App'ta Uluslararasılaştırma (i18n) Başlarken

    GitHub'da Uygulama Şablonu'na bakın.

    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 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.
    • Otomatik oluşturulan türlerle TypeScript desteği sağlayın, otomatik tamamlama ve hata algılamayı iyileştirin.
    • Dinamik yerel algılama ve değiştirme gibi gelişmiş özelliklerden yararlanın.

    React Uygulamasında Intlayer'ı Kurmak İçin Adım Adım Kılavuz

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

    Gerekli paketleri npm kullanarak yükleyin:

    bash
    npm install intlayer react-intlayer react-scripts-intlayer
    • intlayer

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

    • react-intlayer

      Intlayer'ı React uygulamasıyla entegre eden paket. React uluslararasılaştırması için bağlam sağlayıcıları ve hook'lar sağlar.

    • react-scripts-intlayer

      Create React App tabanlı uygulama ile Intlayer'ı entegre etmek için react-scripts-intlayer komutlarını ve eklentileri içerir. Bu eklentiler craco tabanlıdır ve Webpack paketleyici için ek yapılandırma içerir.

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

    Uygulamanızın dillerini yapılandırmak için bir yapılandırma dosyası oluşturun:

    intlayer.config.ts
    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, ara yazılım yönlendirmesi, çerez adları, içerik bildirimlerinizin konumu ve uzantısı ayarlayabilir, Intlayer günlüklerini konsolda devre dışı bırakabilir ve daha fazlasını yapabilirsiniz. Kullanılabilir parametrelerin tam listesi için yapılandırma dokümantasyonuna bakın.

    Adım 3: Intlayer'ı CRA Yapılandırmanızda Entegre Edin

    Betiklerinizi Intlayer kullanacak şekilde değiştirin

    package.json
      "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },

    react-scripts-intlayer betikleri CRACO tabanlıdır. Kendi kurulumunuzu CRACO'nun intlayer eklentisi temel alarak da uygulayabilirsiniz. Örneğe buradan bakın.

    Adım 4: İçeriğinizi Bildirin

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

    src/app.content.tsx
    import { t, type Dictionary } from "intlayer";import React, { type ReactNode } from "react";const appContent = {  key: "app",  content: {    getStarted: t<ReactNode>({      en: (        <>          <code>src/App.tsx</code>'i düzenleyin ve kaydedin        </>      ),      fr: (        <>          Éditez <code>src/App.tsx</code> et enregistrez pour recharger        </>      ),      es: (        <>          Edita <code>src/App.tsx</code> y guarda para recargar        </>      ),    }),    reactLink: {      href: "https://reactjs.org",      content: t({        en: "Learn React",        fr: "Apprendre React",        es: "Aprender React",      }),    },  },} satisfies Dictionary;export default appContent;

    İçerik bildirimleriniz uygulamanızda herhangi bir yerde tanımlanabilir, yeter ki contentDir dizinine dahil edilsinler (varsayılan olarak ./src). Ve içerik bildirim dosyası uzantısıyla eşleşsinler (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

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

    Eğer içerik dosyanız TSX kodu içeriyorsa, içerik dosyanıza import React from "react"; içe aktarmayı düşünün.

    Adım 5: Kodunuzda Intlayer'ı Kullanın

    İçerik sözlüklerinize uygulamanız genelinde erişin:

    src/App.tsx
    import logo from "./logo.svg";import "./App.css";import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => {  const content = useIntlayer("app");  return (    <div className="App">      <img src={logo} className="App-logo" alt="logo" />      {content.getStarted}      <a        className="App-link"        href={content.reactLink.href.value}        target="_blank"        rel="noopener noreferrer"      >        {content.reactLink.content}      </a>    </div>  );};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

    Not: Eğer içeriğinizi bir string özniteliğinde kullanmak istiyorsanız, alt, title, href, aria-label vb. gibi, fonksiyonun değerini çağırmanız gerekir:

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

    useIntlayer hook'u hakkında daha fazla bilgi için dokümantasyona bakın.

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

    İçeriğinizin dilini değiştirmek için, useLocale hook'u tarafından sağlanan setLocale fonksiyonunu kullanabilirsiniz. Bu fonksiyon, uygulamanın yerel ayarını ayarlamanıza ve içeriği buna göre güncellemenize izin verir.

    src/components/LocaleSwitcher.tsx
    import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Dili İngilizce'ye değiştir    </button>  );};

    useLocale hook'u hakkında daha fazla bilgi için dokümantasyona bakın.

    (İsteğe Bağlı) Adım 7: Uygulamanıza Yerelleştirilmiş Yönlendirme Ekleyin

    Bu adımın amacı, her dil için benzersiz rotalar oluşturmaktır. Bu, SEO ve SEO dostu URL'ler için yararlıdır. Örnek:

    plaintext
    - https://example.com/about- https://example.com/es/about- https://example.com/fr/about

    Varsayılan olarak, rotalar varsayılan yerel ayar için öneklenmez. Varsayılan yerel ayarı öneklemek istiyorsanız, yapılandırmanızda middleware.prefixDefault seçeneğini true olarak ayarlayabilirsiniz. Daha fazla bilgi için yapılandırma dokümantasyonuna bakın.

    Uygulamanıza yerelleştirilmiş yönlendirme eklemek için, uygulamanızın rotalarını saran ve yerel tabanlı yönlendirmeyi işleyen bir LocaleRouter bileşeni oluşturabilirsiniz. React Router kullanarak bir örnek aşağıda verilmiştir:

    src/components/LocaleRouter.tsx
    // Gerekli bağımlılıkları ve fonksiyonları içe aktarimport { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Intlayer'dan yardımcı fonksiyonlar ve türler// Intlayer'dan yardımcı fonksiyonlar ve türlerimport type { FC, PropsWithChildren } from "react"; // React fonksiyonel bileşenler ve prop türleriimport { IntlayerProvider } from "react-intlayer"; // Uluslararasılaştırma bağlam sağlayıcısıimport {  BrowserRouter,  Routes,  Route,  Navigate,  useLocation,} from "react-router-dom"; // Navigasyon yönetimi için yönlendirici bileşenleri// Yapılandırmayı Intlayer'dan çıkarconst { internationalization, middleware } = configuration;const { locales, defaultLocale } = internationalization;/** * Yerelleştirmeyi işleyen ve çocukları uygun yerel bağlamla saran bir bileşen. * URL tabanlı yerel algılama ve doğrulama yönetir. */const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({  children,  locale,}) => {  const { pathname, search } = useLocation(); // Geçerli URL yolunu al  // Sağlanmadıysa varsayılan yerel ayara geri dön  const currentLocale = locale ?? defaultLocale;  // Temel bir yol oluşturmak için yoldan yerel öneki kaldır  const pathWithoutLocale = getPathWithoutLocale(    pathname // Geçerli URL yolu  );  /**   * middleware.prefixDefault true ise, varsayılan yerel ayar her zaman öneklenmelidir.   */  if (middleware.prefixDefault) {    // Yerel ayarı doğrula    if (!locale || !locales.includes(locale)) {      // Güncellenmiş yol ile varsayılan yerel ayara yönlendir      return (        <Navigate          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}          replace // Geçerli geçmişi yeni olanla değiştir        />      );    }    // Çocukları IntlayerProvider ile sar ve geçerli yerel ayarı ayarla    return (      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>    );  } else {    /**     * middleware.prefixDefault false olduğunda, varsayılan yerel ayar öneklenmez.     * Geçerli yerel ayar geçerli olduğundan ve varsayılan yerel ayar olmadığından emin ol.     */    if (      currentLocale.toString() !== defaultLocale.toString() &&      !locales        .filter(          (locale) => locale.toString() !== defaultLocale.toString() // Varsayılan yerel ayarı hariç tut        )        .includes(currentLocale) // Geçerli yerel ayar geçerli yerel ayarlar listesinde mi kontrol et    ) {      // Yerel önek olmadan yola yönlendir      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;    }    // Çocukları IntlayerProvider ile sar ve geçerli yerel ayarı ayarla    return (      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>    );  }};/** * Yerel ayarlara özel rotalar ayarlayan bir yönlendirici bileşen. * React Router kullanarak navigasyonu yönetir ve yerelleştirilmiş bileşenleri işler. */export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (  <BrowserRouter>    <Routes>      {locales        .filter(          (locale) => middleware.prefixDefault || locale !== defaultLocale        )        .map((locale) => (          <Route            // Yerel ayarı yakalayan rota deseni (ör. /en/, /fr/) ve sonraki tüm yolları eşleştir            path={`/${locale}/*`}            key={locale}            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Çocukları yerel yönetimle sar          />        ))}      {        // Varsayılan yerel ayar önekleme devre dışıysa, çocukları doğrudan kök yolda işle        !middleware.prefixDefault && (          <Route            path="*"            element={              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>            } // Çocukları yerel yönetimle sar          />        )      }    </Routes>  </BrowserRouter>);

    Ardından, LocaleRouter bileşenini uygulamanızda kullanabilirsiniz:

    src/App.tsx
    import { LocaleRouter } from "./components/LocaleRouter";import type { FC } from "react";// ... AppContent bileşeninizconst App: FC = () => (  <LocaleRouter>    <AppContent />  </LocaleRouter>);

    (İsteğe Bağlı) Adım 8: Yerel Ayar Değiştiğinde URL'yi Değiştirin

    Yerel ayar değiştiğinde URL'yi değiştirmek için, useLocale hook'u tarafından sağlanan onLocaleChange prop'unu kullanabilirsiniz. Paralel olarak, URL yolunu güncellemek için react-router-dom'dan useLocation ve useNavigate hook'larını kullanabilirsiniz.

    src/components/LocaleSwitcher.tsx
    import { useLocation, useNavigate } from "react-router-dom";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "react-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { pathname, search } = useLocation(); // Geçerli URL yolunu al. Örnek: /fr/about?foo=bar  const navigate = useNavigate();  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (locale) => {      // Güncellenmiş yerel ayar ile URL'yi oluştur      // Örnek: /es/about?foo=bar      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);      // URL yolunu güncelle      navigate(pathWithLocale);    },  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <a            href={getLocalizedUrl(location.pathname, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}            key={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 İspanyolca'da Francés - örn. */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* İngilizce'de dil - örn. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </a>        ))}      </div>    </div>  );};

    Dokümantasyon referansları:

    (İsteğe Bağlı) Adım 9: HTML Dil ve Yön Özniteliklerini Değiştirin

    Uygulamanız birden fazla dili desteklediğinde, <html> etiketinin lang ve dir özniteliklerini geçerli yerel ayarla eşleşecek şekilde güncellemek çok önemlidir.

    Bunu otomatik olarak işlemek için bir hook oluşturabilirsiniz.

    Hook'u Uygulama

    HTML özniteliklerini yönetmek için özel bir hook oluşturun. Hook, yerel ayar değişikliklerini dinler ve öznitelikleri buna göre günceller:

    src/hooks/useI18nHTMLAttributes.tsx
    import { useEffect } from "react";import { useLocale } from "react-intlayer";import { getHTMLTextDir } from "intlayer";/** * Geçerli yerel ayara göre HTML <html> etiketinin `lang` ve `dir` özniteliklerini günceller. * - `lang`: Tarayıcılara ve arama motorlarına sayfanın dilini bildirir. * - `dir`: Arapça veya İbranice gibi diller için 'rtl' gibi doğru okuma sırasını sağlar. * * Bu dinamik güncelleme, uygun metin işleme, erişilebilirlik ve SEO için gereklidir. */export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    // Dil özniteliğini geçerli yerel ayara güncelle    document.documentElement.lang = locale;    // Geçerli yerel ayara göre metin yönünü ayarla    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

    Hook'u Uygulamanızda Kullanma

    HTML özniteliklerinin yerel ayar her değiştiğinde güncellenmesi için hook'u ana bileşeninizde entegre edin:

    src/App.tsx
    import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";import "./App.css";const AppContent: FC = () => {  // Hook'u kullanarak yerel ayara göre <html> etiketinin lang ve dir özniteliklerini güncelleyin.  useI18nHTMLAttributes();  // ... Bileşeninizin geri kalanı};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

    Bu değişiklikleri uygulayarak, uygulamanız:

    • Dil (lang) özniteliğinin SEO ve tarayıcı davranışı için doğru geçerli yerel ayarı yansıtmasını sağlar.
    • Metin yönü (dir) özniteliğini yerel ayara göre ayarlar, Arapça veya İbranice gibi farklı okuma sırasına sahip diller için okunabilirliği geliştirir.
    • Daha erişilebilir bir deneyim sağlar, çünkü yardımcı teknolojiler bu özniteliklere optimum şekilde çalışmak için güvenir.

    TypeScript'i Yapılandırın

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

    alt text

    alt text

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

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

    Git Yapılandırması

    Intlayer tarafından oluşturulan dosyaları yok saymanız önerilir. Bu, onları Git deponuza commit etmenizi önler.

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

    .gitignore
    # Intlayer tarafından oluşturulan dosyaları yok say.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 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 Gidin

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

    Doküman Geçmişi

    Sürüm Tarih Değişiklikler
    5.5.10 2025-06-29 Geçmiş başlatıldı
    Yaklaşan Intlayer sürümleri hakkında bildirim alın