Intlayer kullanarak Vite ve Vanilla JS web sitenizi çevirin | Uluslararasılaştırma (i18n)

İçindekiler

Neden alternatifler yerine Intlayer?

'i18next' veya 'i18n.js' gibi ana çözümlerle karşılaştırıldığında Intlayer, aşağıdaki gibi entegre optimizasyonlarla gelen bir çözümdür:

Bir Vite ve Vanilla JS Uygulamasında Intlayer Kurulumu İçin Adım Adım Kılavuz

1. 1

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

   npm kullanarak gerekli paketleri yükleyin:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install intlayer vanilla-intlayernpm install vite-intlayer --save-devnpx intlayer init

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

   • vanilla-intlayer Intlayer'ı saf JavaScript / TypeScript uygulamalarıyla entegre eden paket. Bir pub/sub singleton (IntlayerClient) ve geri çağırma tabanlı yardımcılar (useIntlayer, useLocale, vb.) sağlar, böylece uygulamanızın herhangi bir bölümü bir UI çerçevesine bağlı kalmadan yerel ayar değişikliklerine tepki verebilir.

   • vite-intlayer Intlayer'ı Vite paketleyici ile entegre etmek için Vite eklentisini ve kullanıcının tercih ettiği yerel ayarı algılamak, çerezleri yönetmek ve URL yönlendirmesini işlemek için ara yazılımı içerir.

2. 2

   Projenizin Yapılandırılması

   Ugulamanı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'leri, ara yazılım yönlendirmesini, çerez adlarını, içerik bildirimlerinizin konumunu ve uzantısını ayarlayabilir, konsoldaki Intlayer günlüklerini devre dışı bırakabilir ve daha fazlasını yapabilirsiniz. Mevcut parametrelerin tam listesi için yapılandırma belgelerine bakın.

3. 3

   Intlayer'ı Vite Yapılandırmanıza Entegre Edin

   Yapılandırmanıza intlayer eklentisini ekleyin.

   vite.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [intlayer()],
   });

   intlayer() Vite eklentisi, Intlayer'ı Vite ile entegre etmek için kullanılır. İçerik bildirimi dosyalarının oluşturulmasını sağlar ve bunları geliştirme modunda izler. Vite uygulaması içinde Intlayer ortam değişkenlerini tanımlar. Ayrıca, performansı optimize etmek için takma adlar (aliases) sağlar.

4. 4

   Giriş noktanızda Intlayer'ı başlatın

   Küresel yerel ayar singleton'ının hazır olması için herhangi bir içerik işlenmeden önce installIntlayer() işlevini çağırın.

   src/main.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { installIntlayer } from "vanilla-intlayer";// Herhangi bir i18n içeriği işlenmeden önce çağrılmalıdır.installIntlayer();// Uygulama modüllerinizi içe aktarın ve çalıştırın.import "./app.js";

   Ayrıca md() içerik bildirimlerini (Markdown) kullanıyorsanız, markdown oluşturucuyu da yükleyin:

   src/main.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";installIntlayer();installIntlayerMarkdown();import "./app.js";

5. 5

   İçeriğinizi Bildirin

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

   src/app.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { insert, t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Vanilla",
   
       viteLogoLabel: t({
         en: "Vite Logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
   
       count: insert(
         t({
           en: "count is {{count}}",
           fr: "le compte est {{count}}",
           es: "el recuento es {{count}}",
         })
       ),
   
       readTheDocs: t({
         en: "Click on the Vite logo to learn more",
         fr: "Cliquez sur le logo Vite pour en savoir plus",
         es: "Daha fazlasını öğrenmek için Vite logosuna tıklayın",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;

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

   Daha fazla ayrıntı için içerik bildirimi belgelerine bakın.

6. 6

   JavaScript'inizde Intlayer Kullanın

   vanilla-intlayer, react-intlayer yüzey API'sini yansıtır: useIntlayer(key, locale?) doğrudan çevrilmiş içeriği döndürür. Yerel ayar değişikliklerine abone olmak için sonuç üzerinde .onChange() işlevini zincirleyin - bir React yeniden oluşturmasının açık eşdeğeri.

   src/main.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { installIntlayer, useIntlayer } from "vanilla-intlayer";installIntlayer();// Mevcut yerel ayar için başlangıç içeriğini alın.// Yerel ayar her değiştiğinde bildirim almak için .onChange() işlevini zincirleyin.const content = useIntlayer("app").onChange((newContent) => {  // Yalnızca etkilenen DOM düğümlerini yeniden oluşturun veya yamalayın  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(    newContent.title  );  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =    String(newContent.readTheDocs);});// Başlangıç oluşturmadocument.querySelector<HTMLHeadingElement>("h1")!.textContent = String(  content.title);document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =  String(content.readTheDocs);

   Yaprak değerleri String() içine sararak onlara dize olarak erişin, bu da düğümün toString() yöntemini çağırır ve çevrilmiş metni döndürür.

   Yerel bir HTML özelliği (örn. alt, aria-label) için değere ihtiyacınız olduğunda, doğrudan .value kullanın:

   typescript

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   img.alt = content.viteLogoLabel.value;

7. 7

   İçeriğinizin dilini değiştirin

   İsteğe bağlı

   İçeriğinizin dilini değiştirmek için useLocale tarafından sunulan setLocale işlevini kullanın.

   src/locale-switcher.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { getLocaleName } from "intlayer";import { useLocale } from "vanilla-intlayer";export function setupLocaleSwitcher(container: HTMLElement): () => void {  const { locale, availableLocales, setLocale, subscribe } = useLocale();  const select = document.createElement("select");  select.setAttribute("aria-label", "Language");  const render = (currentLocale: string) => {    select.innerHTML = availableLocales      .map(        (loc) =>          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>            ${getLocaleName(loc)}          </option>`      )      .join("");  };  render(locale);  container.appendChild(select);  select.addEventListener("change", () => setLocale(select.value as any));  // Başka bir yerden yerel ayar değiştiğinde açılır menüyü senkronize tutun  return subscribe((newLocale) => render(newLocale));}

8. 8

   Markdown ve HTML içeriği oluşturun

   İsteğe bağlı

   Intlayer md() ve html() içerik bildirimlerini destekler. Vanilla JS'de, derlenmiş çıktı innerHTML aracılığıyla ham HTML olarak eklenir.

   HTML'yi derleyin ve ekleyin:

   src/main.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import {  compileMarkdown,  installIntlayerMarkdown,  useIntlayer,} from "vanilla-intlayer";installIntlayerMarkdown();const content = useIntlayer("app").onChange((newContent) => {  const el = document.querySelector<HTMLDivElement>(".edit-note")!;  el.innerHTML = compileMarkdown(String(newContent.editNote));});document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =  compileMarkdown(String(content.editNote));

   TIP

   String(content.editNote), IntlayerNode üzerinde ham Markdown dizesini döndüren toString() işlevini çağırır. Bir HTML dizesi almak için bunu compileMarkdown'a geçirin, ardından innerHTML aracılığıyla ayarlayın.

   WARNING

   innerHTML'i yalnızca güvenilir içerikle kullanın. Markdown kullanıcı girişinden geliyorsa, önce onu temizleyin (örn. DOMPurify ile). Bir temizleme oluşturucusunu dinamik olarak yükleyebilirsiniz:

   typescript

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";await installIntlayerMarkdownDynamic(async () => {  const DOMPurify = await import("dompurify");  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));});

9. 9

   Uygulamanıza yerelleştirilmiş Yönlendirme ekleyin

   İsteğe bağlı

   Her dil için benzersiz yollar oluşturmak için (SEO için yararlıdır), sunucu tarafı yerel ayar algılaması için Vite yapılandırmanızda intlayerProxy kullanabilirsiniz.

   İlk olarak, Vite yapılandırmanıza intlayerProxy ekleyin:

   Üretimde intlayerProxy kullanmak için vite-intlayer'ı devDependencies'dan dependencies'e taşımanız gerektiğini unutmayın.

   vite.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { defineConfig } from "vite";
   import { intlayer, intlayerProxy } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayerProxy(), // ilk sıraya yerleştirilmelidir
       intlayer(),
     ],
   });

10. 10

    Yerel ayar değiştiğinde URL'yi değiştirin

    İsteğe bağlı

    Yerel ayar değiştiğinde tarayıcı URL'sini güncellemek için Intlayer'ı yükledikten sonra useRewriteURL() işlevini çağırın:

    src/main.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { installIntlayer, useRewriteURL } from "vanilla-intlayer";installIntlayer();// URL'yi hemen ve sonraki her yerel ayar değişikliğinde yeniden yazar.// Temizlik için bir abonelikten çıkma işlevi döndürür.const stopRewriteURL = useRewriteURL();

11. 11

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

    İsteğe bağlı

    Erişilebilirlik ve SEO için <html> etiketinin lang ve dir özniteliklerini mevcut yerel ayara uyacak şekilde güncelleyin.

    src/main.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { getHTMLTextDir } from "intlayer";import { installIntlayer, useLocale } from "vanilla-intlayer";installIntlayer();useLocale({  onLocaleChange: (locale) => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  },});

12. 12

    Yerel ayar başına sözlükleri tembel yükleyin

    İsteğe bağlı

    Büyük uygulamalar için her yerel ayarın sözlüğünü kendi yığınına bölmek isteyebilirsiniz. Vite'in dinamik import() işleviyle birlikte useDictionaryDynamic kullanın:

    src/app.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";installIntlayer();const unsubscribe = useDictionaryDynamic(  {    en: () => import("../.intlayer/dictionaries/en/app.mjs"),    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),    es: () => import("../.intlayer/dictionaries/es/app.mjs"),  },  "app").onChange((content) => {  document.querySelector("h1")!.textContent = String(content.title);});

    Her yerel ayarın paketi yalnızca o yerel ayar etkinleştirildiğinde getirilir ve sonuç önbelleğe alınır - aynı yerel ayara sonraki geçişler anlıktır.

13. 13

    Bileşenlerinizin içeriğini dışa aktarın

    İsteğe bağlı

    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 dışa aktarmak için bir derleyici / ayıştırıcı önerir.

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

    intlayer.config.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Geri kalan yapılandırmanız  compiler: {    /**     * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.     */    enabled: true,    /**     * Çıktı dosyaları yolunu tanımlar     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Dönüştürüldükten sonra bileşenlerin kaydedilip kaydedilmeyeceğini belirtir.     * Bu şekilde, 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ı ön eki     */    dictionaryKeyPrefix: "",  },};export default config;

    Extract komutuBabel derleyicisi

    Bileşenlerinizi dönüştürmek ve içeriği ayıklamak için ayıştırıcıyı çalıştırın

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npx intlayer extract

    intlayerCompiler eklentisini dahil etmek için vite.config.ts dosyanızı güncelleyin:

    vite.config.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Derleyici eklentisini ekler ],});

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npm run build # veya npm run dev

(İsteğe bağlı) Sitemap ve robots.txt (build zamanı üretimi)

Intlayer, generateSitemap ve getMultilingualUrls ile tarayıcılar için çok dilli sitemap.xml ve robots.txt üretip bunları public/ klasörüne otomatik yazmanıza yardımcı olur. Genelde Vite’tan önce küçük bir Node betiği çalıştırılır (ör. npm predev / prebuild kancaları).

Sitemap

Intlayer sitemap oluşturucusu yerel ayarlarınıza uyar ve tarayıcılar için metadata ekler.

Üretilen sitemap xhtml:link (hreflang) ad alanını destekler. Düz URL listesi yerine, her sayfanın tüm dil sürümleri çift yönlü bağlanır (ör. /about, /fr/about veya /about?lang=fr - yönlendirme moduna bağlı).

Robots.txt

getMultilingualUrls kullanarak Disallow kurallarının hassas yolların tüm yerelleştirilmiş varyantlarını kapsamasını sağlayın.

1. Proje köküne generate-seo.mjs ekleyin

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Betik intlayer içe aktarabilmeli; paket kurulu olmalı. Üretimde ortam değişkeni SITE_URL ayarlayın (ör. CI).

Node ESM için generate-seo.mjs tercih edin. generate-seo.js kullanıyorsanız package.json içinde "type": "module" veya ESM’yi başka şekilde etkinleştirin.

2. Betiği Vite’tan önce çalıştırın

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

pnpm veya yarn kullanıyorsanız komutları uyarlayın. CI’dan da çağrılabilir.

TypeScript'i Yapılandırın

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

{  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaların yoksayılması önerilir. Bu, onları Git deponuza göndermekten kaçınmanıza olanak tanır.

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 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ğına dair daha fazla ayrıntı için Intlayer VS Code Uzantısı belgelerine bakın.

Daha Fazlasına Gidin

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