Intlayer ile Create React App çevirin | Uluslararasılaştırma (i18n)

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

Intlayer Nedir?

react-i18next veya i18next gibi ana çözümlere kıyasla, Intlayer aşağıdaki gibi entegre optimizasyonlarla gelen bir çözümdür:

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

1. 1

   Bağımlılıkları Yükleyin

   Gerekli paketleri npm kullanarak yükleyin:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npx intlayer init --interactive
   

   --interactive bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız intlayer-cli init kullanın.

   Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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.

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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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.

3. 3

   Intlayer'ı CRA Yapılandırmanızda Entegre Edin

   Betiklerinizi Intlayer kullanacak şekilde değiştirin

   package.json

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

4. 4

   İçeriğinizi Bildirin

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

   src/app.content.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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,cjs,md,mdx,yaml,yml}).

   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.

5. 5

   Kodunuzda Intlayer'ı Kullanın

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

   src/App.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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:

   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 hook'u hakkında daha fazla bilgi için dokümantasyona bakın.

6. 6

   İçeriğinizin Dilini Değiştirin

   İsteğe bağlı

   İç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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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.

7. 7

   Uygulamanıza Yerelleştirilmiş Yönlendirme Ekleyin

   İsteğe bağlı

   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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   - 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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   // Gerekli bağımlılıkları ve fonksiyonları içe aktar
   import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Intlayer'dan yardımcı fonksiyonlar ve türler
   // Intlayer'dan yardımcı fonksiyonlar ve türler
   import type { FC, PropsWithChildren } from "react"; // React fonksiyonel bileşenler ve prop türleri
   import { 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 çıkar
   const { 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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

8. 8

   Yerel Ayar Değiştiğinde URL'yi Değiştirin

   İsteğe bağlı

   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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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ı:

   • useLocale hook'u
   • getLocaleName hook'u
   • getLocalizedUrl hook'u
   • getHTMLTextDir hook'u
   • hrefLang özniteliği
   • lang özniteliği
   • dir özniteliği
   • aria-current özniteliği

9. 9

   HTML Dil ve Yön Özniteliklerini Değiştirin

   İsteğe bağlı

   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.

   • Accessibility: Ekran okuyucuları ve yardımcı teknolojiler, içeriği doğru şekilde telaffuz etmek ve yorumlamak için lang özniteliğine dayanır.
   • Text Rendering: dir (direction) özniteliği, metnin doğru sırada renderlenmiş olmasını sağlar (örneğin, İngilizce için soldan sağa, Arapça veya İbranice için sağdan sola), bu da okunabilirlik için gereklidir.
   • SEO: Arama motorları, sayfanızın dilini belirlemek için lang özniteliğini kullanır ve arama sonuçlarında doğru yerelleştirilmiş içeriği sunmaya yardımcı olur.

   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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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.

TypeScript yapılandırmanızın otomatik 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 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:

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

Sıkça Sorulan Sorular