Intlayer Kullanarak Tanstack Start + Solid.js Web Sitenizi Çevirin | Uluslararasılaştırma (i18n)

İçindekiler

Bu kılavuz, Solid.js içeren Tanstack Start projelerinde sorunsuz uluslararasılaştırma, yerel ayara duyarlı yönlendirme, TypeScript desteği ve modern geliştirme uygulamaları için Intlayer'ı nasıl entegre edeceğinizi gösterir.

Neden alternatifler yerine Intlayer?

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

Tanstack Start Uygulamasında Intlayer Kurulumu İçin Adım Adım Kılavuz

VideoKodDemo

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-tanstack-start-solid.vercel.app

Open embedded page in fullscreen

GitHub'daki Uygulama Şablonuna göz atın.

1. 1

   Proje Oluşturma

   Öncelikle, TanStack Start web sitesindeki Yeni Proje Başlat kılavuzunu izleyerek yeni bir TanStack Start projesi oluşturun.

2. 2

   Intlayer Paketlerini Kurun

   Tercih ettiğiniz paket yöneticisini kullanarak gerekli paketleri kurun:

   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 solid-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • solid-intlayer Intlayer'ı Solid uygulamasına entegre eden paket. Solid uluslararasılaştırması için bağlam sağlayıcıları (context providers) ve hook'lar sunar.

   • 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ı (middleware) içerir.

3. 3

   Projenizin Yapılandırılması

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

   intlayer.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { IntlayerConfig } from "intlayer";
   
   import { Locales } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       defaultLocale: Locales.ENGLISH,
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     },
   };
   
   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ı yapılandırabilir, konsoldaki Intlayer günlüklerini devre dışı bırakabilir ve daha fazlasını yapabilirsiniz. Kullanılabilir parametrelerin tam listesi için yapılandırma dokümantasyonuna bakın.

4. 4

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

   Bite yapılandırmanıza intlayer eklentisini ekleyin:

   vite.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { intlayer } from "vite-intlayer";
   import { defineConfig } from "vite";
   import { devtools } from "@tanstack/devtools-vite";
   import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
   import solidPlugin from "vite-plugin-solid";
   
   export default defineConfig({
     plugins: [
       devtools(),
       tanstackStart({
         router: {
           routeFileIgnorePattern:
             ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
         },
       }),
       solidPlugin({ ssr: true }),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

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

5. 5

   Kök Düzeni (Root Layout) Oluşturma

   Geçerli yerel ayarı algılamak için useParams kullanarak ve html etiketinde lang ve dir özelliklerini ayarlayarak kök düzeninizi uluslararasılaştırmayı destekleyecek şekilde yapılandırın.

   src/routes/__root.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import {
     HeadContent,
     Scripts,
     createRootRouteWithContext,
     getRouteApi,
   } from "@tanstack/solid-router";
   import { HydrationScript } from "solid-js/web";
   import { Suspense, type ParentComponent } from "solid-js";
   import { IntlayerProvider } from "solid-intlayer";
   import { defaultLocale, getHTMLTextDir } from "intlayer";
   
   const localeRoute = getRouteApi("/{-$locale}");
   
   export const Route = createRootRouteWithContext()({
     shellComponent: RootComponent,
   });
   
   const RootComponent: ParentComponent = (props) => {
     const params = localeRoute.useParams();
     const locale = params()?.locale ?? defaultLocale;
   
     return (
       <html dir={getHTMLTextDir(locale)} lang={locale}>
         <head>
           <HydrationScript />
           <HeadContent />
         </head>
         <body>
           <IntlayerProvider locale={locale}>
             <Suspense>{props.children}</Suspense>
           </IntlayerProvider>
           <Scripts />
         </body>
       </html>
     );
   };
   

6. 6

   Yerel Ayar Düzeni Oluşturma

   Yerel ayar önekini işleyen ve doğrulama gerçekleştiren bir düzen oluşturun. Bu düzen, yalnızca geçerli yerel ayarların işlenmesini sağlayacaktır.

   Rota düzeyinde yerel ayar önekini doğrulamanız gerekmiyorsa bu adım isteğe bağlıdır.

   src/routes/{-$locale}/route.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { createFileRoute, Outlet, redirect } from "@tanstack/solid-router";
   import { validatePrefix } from "intlayer";
   
   export const Route = createFileRoute("/{-$locale}")({
     beforeLoad: ({ params }) => {
       const localeParam = params.locale;
   
       // Yerel ayar önekini doğrula
       const { isValid, localePrefix } = validatePrefix(localeParam);
   
       if (!isValid) {
         throw redirect({
           to: "/{-$locale}/404",
           params: { locale: localePrefix },
           replace: true,
         });
       }
     },
     component: Outlet,
   });
   

   Burada, {-$locale} geçerli yerel ayarla değiştirilen dinamik bir rota parametresidir. Bu gösterim, bu slotu isteğe bağlı hale getirerek 'prefix-no-default' vb. yönlendirme modlarıyla çalışmasına olanak tanır.

   Aynı rotada birden fazla dinamik segment kullanırsanız bu slotun sorunlara neden olabileceğini unutmayın (ör: /{-$locale}/other-path/$anotherDynamicPath/...). 'prefix-all' modu için slotu $locale olarak değiştirmeyi tercih edebilirsiniz. 'no-prefix' veya 'search-params' modu için slotu tamamen kaldırabilirsiniz.

7. 7

   İçeriğinizi Bildirin

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

   src/contents/page.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { Dictionary } from "intlayer";
   
   import { t } from "intlayer";
   
   const appContent = {
     content: {
       links: {
         about: t({
           en: "About",
           es: "Acerca de",
           fr: "À propos",
         }),
         home: t({
           en: "Home",
           es: "Inicio",
           fr: "Accueil",
         }),
       },
       meta: {
         title: t({
           en: "Welcome to Intlayer + TanStack Router",
           es: "Bienvenido a Intlayer + TanStack Router",
           fr: "Bienvenue à Intlayer + TanStack Router",
         }),
         description: t({
           en: "This is an example of using Intlayer with TanStack Router",
           es: "Este es un ejemplo de uso de Intlayer con TanStack Router",
           fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router",
         }),
       },
     },
     key: "app",
   } satisfies Dictionary;
   
   export default appContent;
   

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

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

8. 8

   Yerel Ayara Duyarlı Bileşenleri ve Hook'ları Kullanın

   Yerel ayara duyarlı navigasyon için bir LocalizedLink bileşeni oluşturun:

   src/components/LocalizedLink.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { Link, type LinkProps } from "@tanstack/solid-router";
   import { getPrefix } from "intlayer";
   import { useLocale } from "solid-intlayer";
   import type { JSX } from "solid-js";
   
   export const LOCALE_ROUTE = "{-$locale}" as const;
   
   export type RemoveLocaleParam<TVal> = TVal extends string
     ? RemoveLocaleFromString<TVal>
     : TVal;
   
   export type To = RemoveLocaleParam<LinkProps["to"]>;
   
   type CollapseDoubleSlashes<TString extends string> =
     TString extends `${infer THead}//${infer TTail}`
       ? CollapseDoubleSlashes<`${THead}/${TTail}`>
       : TString;
   
   export type LocalizedLinkProps = Omit<LinkProps, "to"> & {
     to?: To;
   } & JSX.AnchorHTMLAttributes<HTMLAnchorElement>;
   
   type RemoveAll<
     TString extends string,
     TSub extends string,
     McPherson,
   > = TString extends `${infer THead}${TSub}${infer TTail}`
     ? RemoveAll<`${THead}${TTail}`, TSub>
     : TString;
   
   type RemoveLocaleFromString<TString extends string> = CollapseDoubleSlashes<
     RemoveAll<TString, typeof LOCALE_ROUTE>
   >;
   
   export const LocalizedLink = (props: LocalizedLinkProps) => {
     const { locale } = useLocale();
   
     return (
       <Link
         {...props}
         params={{
           locale: getPrefix(locale()).localePrefix,
           ...(typeof props.params === "object" ? props.params : {}),
         }}
         to={`/${LOCALE_ROUTE}${props.to ?? ""}` as LinkProps["to"]}
       />
     );
   };
   

   Bu bileşen iki amaca hizmet eder:

   • URL'den gereksiz {-$locale} önekini kaldırmak.
   • Kullanıcının doğrudan yerelleştirilmiş rotaya yönlendirilmesini sağlamak için yerel ayar parametresini URL'ye enjekte etmek.

   Ardından, programatik navigasyon için bir useLocalizedNavigate hook'u oluşturabiliriz:

   src/hooks/useLocalizedNavigate.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { useNavigate } from "@tanstack/solid-router";
   import { getLocalizedUrl } from "intlayer";
   import { useLocale } from "solid-intlayer";
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
     const { locale } = useLocale();
   
     const localizedNavigate = (to: string) => {
       const localizedTo = getLocalizedUrl(to, locale());
       return navigate({ to: localizedTo });
     };
   
     return localizedNavigate;
   };
   

9. 9

   Sayfalarınızda Intlayer'ı Kullanın

   Varsayılan olarak useIntlayer kullanın: bileşenler içinde içerik okumanın önerilen yoludur ve derleyici onu render edilen yerel ayara çözer. getIntlayer / getIntlayerAsync işlevlerine yalnızca Solid ağacının dışında başvurun: rota head'i, loader'lar ve sunucu işlevleri.

   Uygulamanız genelinde içerik sözlüklerinize erişin:

   Yerelleştirilmiş Ana Sayfa

   src/routes/{-$locale}/index.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { createFileRoute } from "@tanstack/solid-router";
   import { useIntlayer } from "solid-intlayer";
   import { LocalizedLink } from "@/components/LocalizedLink";
   
   export const Route = createFileRoute("/{-$locale}/")({
     component: RouteComponent,
   });
   
   function RouteComponent() {
     const content = useIntlayer("index-page");
   
     return (
       <main>
         <h1>{content.heroTitle}</h1>
         <p>{content.heroDesc}</p>
         <div>
           <LocalizedLink to="/">{content.navHome}</LocalizedLink>
           <LocalizedLink to="/about">{content.navAbout}</LocalizedLink>
         </div>
       </main>
     );
   }
   

   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)}" />
   

   Solid'de, useIntlayer reaktif içerik döndürür (örneğin, content). Özelliklerine doğrudan erişebilirsiniz.

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

10. 10

    Yerel Ayar Değiştirici Bileşeni Oluşturma

    Kullanıcıların dilleri değiştirmesine olanak tanıyan bir bileşen oluşturun:

    src/components/LocaleSwitcher.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { useLocation } from "@tanstack/solid-router";
    import { getLocaleName, getPathWithoutLocale, getPrefix } from "intlayer";
    import { For } from "solid-js";
    import { useIntlayer, useLocale } from "solid-intlayer";
    import { LocalizedLink, type To } from "./LocalizedLink";
    
    export const LocaleSwitcher = () => {
      const content = useIntlayer("locale-switcher");
      const location = useLocation();
    
      const { availableLocales, locale, setLocale } = useLocale();
    
      const pathWithoutLocale = () => getPathWithoutLocale(location().pathname);
    
      return (
        <div class="flex flex-row gap-2">
          <For each={availableLocales}>
            {(localeEl) => (
              <LocalizedLink
                aria-current={localeEl === locale() ? "page" : undefined}
                onClick={() => setLocale(localeEl)}
                params={{ locale: getPrefix(localeEl).localePrefix }}
                to={pathWithoutLocale() as To}
              >
                {getLocaleName(localeEl)}
              </LocalizedLink>
            )}
          </For>
        </div>
      );
    };
    
    export default LocaleSwitcher;
    

    Solid'de, useLocaledan gelen locale bir signal accessor'dur. Reaktif olarak geçerli değerini okumak için locale() (parantezli) kullanın.

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

11. 11

    HTML Özniteliklerinin Yönetimi

    Adım 5'te görüldüğü gibi, kök bileşeninizde useParams kullanarak html etiketinin lang ve dir özniteliklerini yönetebilirsiniz. Bu, hem sunucuda hem de istemcide doğru özniteliklerin ayarlanmasını sağlar.

    src/routes/__root.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    const RootComponent: ParentComponent = (props) => {
      const params = localeRoute.useParams();
      const locale = params()?.locale ?? defaultLocale;
    
      return (
        <html dir={getHTMLTextDir(locale)} lang={locale}>
          {/* ... */}
        </html>
      );
    };
    

    ---

12. 12

    Ara Yazılım Ekleme

    Uygulamanıza sunucu tarafı yönlendirmesi eklemek için intlayerProxyyi de kullanabilirsiniz. Bu eklenti, URL'ye göre geçerli yerel ayarı otomatik olarak algılayacak ve uygun yerel ayar çerezini ayarlayacaktır. Herhangi bir yerel ayar belirtilmemişse, eklenti kullanıcının tarayıcı dili tercihlerine göre en uygun yerel ayarı belirleyecektir. Hiçbir yerel ayar algılanmazsa varsayılan yerel ayara yönlendirecektir.

    Üretimde intlayerProxyyi kullanmak için vite-intlayer paketini devDependenciesdan dependenciese taşımanız gerektiğini unutmayın.

    Intlayer v9 sürümünden itibaren, intlayerProxy() doğrudan intlayer() plugin'ine dahil edilmiştir ve routing.enableProxy seçeneği aracılığıyla varsayılan olarak etkinleştirilir (varsayılan olarak true). Aşağıda gösterildiği gibi ayrı olarak kaydı artık isteğe bağlıdır; geriye dönük uyumluluk ve plugin sırasını kontrol etmesi gereken kurulumlar için tutulur. Devre dışı bırakmak için routing.enableProxy: false olarak ayarlayın. v9 sürüm notlarına bakın.

    vite.config.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
    import solid from "vite-plugin-solid";
    import { nitro } from "nitro/vite";
    import { defineConfig } from "vite";
    import { intlayer } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        nitro(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
        tanstackStart({
          router: {
            routeFileIgnorePattern:
              ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
          },
        }),
        solid(),
      ],
    });
    

    ---

13. 13

    Meta Verilerinizi Uluslararasılaştırın

    Statik çözümlemeDinamik çözümlemeÖnbellekli dinamik çözümleme

    getIntlayer, tüm bildirilen yerel ayarları içeren birleştirilmiş sözlük üzerinden senkron olarak çözümlenir. head senkron kalır ve hiçbir şey beklenmez, ancak tüm çok dilli sözlük tarayıcıya gönderilen rota parçasına dahil edilir.

    src/routes/{-$locale}/index.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createFileRoute } from "@tanstack/solid-router";
    import {
      defaultLocale,
      getIntlayer,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // The path for this route
    
        const metaContent = getIntlayer("app", locale);
    
        return {
          links: [
            // Canonical link: Points to the current localized page
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Tell Google about all localized versions
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: For users in unmatched languages
            // Define the default fallback locale (usually your primary language)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Küçük meta veri sözlükleri, az sayıda yerel ayar veya prototipleme aşaması için idealdir.

    getIntlayerAsync (v9.4 sürümünden itibaren kullanılabilir) getIntlayer gibi davranır, ancak build eklentisi onu birleştirilmiş sözlük yerine .intlayer/dynamic_dictionaries/ içindeki yerel ayar başına parçaya yönlendirir. Böylece bir sayfa yalnızca render ettiği yerel ayarı gönderir. Bu parça talep üzerine yüklendiğinden head async hâle gelir:

    src/routes/{-$locale}/index.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createFileRoute } from "@tanstack/solid-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: async ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // The path for this route
    
        const metaContent = await getIntlayerAsync("app", locale);
    
        return {
          links: [
            // Canonical link: Points to the current localized page
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Tell Google about all localized versions
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: For users in unmatched languages
            // Define the default fallback locale (usually your primary language)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Bir head birden fazla sözlük okuyorsa bunları Promise.all ile çözümleyin; her getIntlayerAsync çağrısını ayrı satırda beklemek, istekleri paralel çalıştırmak yerine zincirler.

    Ödün: dinamik import, head çalışırken, belge render'ının kritik yolunda çözümlenir. Soğuk bir rotada bu, head'i birkaç milisaniye geciktirir ve LCP'yi bir miktar kötüleştirebilir.

    Sözlüğü rotanın loader'ında çözümleyin ve head içinde loaderData üzerinden geri okuyun. Eşleşen rotaların loader'ları paralel çalışır ve staleTime: Infinity, TanStack Router'a sonucun hiçbir zaman bayatlamayacağını söyler, böylece yerel ayar başına parça bir kez çözümlenir, sonrasında router önbelleğinden sunulur ve head senkron kalır.

    src/routes/{-$locale}/index.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createFileRoute } from "@tanstack/solid-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      // Resolved in parallel with the other matched routes, off the head critical path
      loader: async ({ params }) => {
        const { locale = defaultLocale } = params;
    
        return { metaContent: await getIntlayerAsync("app", locale) };
      },
      // The dictionary never changes for a given locale: resolve the chunk once
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // The path for this route
    
        return {
          links: [
            // Canonical link: Points to the current localized page
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Tell Google about all localized versions
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: For users in unmatched languages
            // Define the default fallback locale (usually your primary language)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: loaderData?.metaContent.title },
            {
              name: "description",
              content: loaderData?.metaContent.meta.description,
            },
          ],
        };
      },
    });
    

    head, loader tamamlanmadan önce çağrılabilir; bu nedenle loaderData muhtemelen undefined olarak tiplenir. Optional chaining'i koruyun veya yedek bir başlık döndürün.

    Yerel ayar başına parçayı, bedelini head kritik yolunda ödemeden korursunuz. Bedeli geliştirici deneyimidir: içeriğin loader'dan head'e loaderData üzerinden açıkça taşınması gerekir.

    Hangi çözümlemeyi seçmeliyim?

    Tüm tablo içeriğini göster

    Tüm tablo içeriğini göster

    Tüm veri içeriğini net bir şekilde görmek için tabloyu modalde açın

    	Statik çözümleme	Dinamik çözümleme	Önbellekli dinamik çözümleme
    API	getIntlayer	getIntlayerAsync (v9.4+)	loader içinde getIntlayerAsync (v9.4+)
    head imzası	senkron	async	senkron, loaderData okur
    Gönderilen yerel ayarlar	bildirilen tüm yerel ayarlar	yalnızca istenen yerel ayar	yalnızca istenen yerel ayar
    İstemci gezinmeleri	çözümlenecek bir şey yok	her eşleşmede yeniden çalışır	router önbelleğinden sunulur
    Geliştirici deneyimi	en basiti	tek bir await	içerik loaderData üzerinden taşınır

    ---

14. 14

    Sunucu aksiyonlarınızda yerel ayarı alın

    Sunucu aksiyonlarınızın veya API uç noktalarınızın içinden geçerli yerel ayara erişmek isteyebilirsiniz. Bunu intlayerdan getLocale yardımcısını kullanarak yapabilirsiniz.

    İşte TanStack Start'ın sunucu fonksiyonlarını kullanan bir örnek:

    src/routes/{-$locale}/index.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createServerFn } from "@tanstack/solid-start";
    import {
      getRequestHeader,
      getRequestHeaders,
    } from "@tanstack/solid-start/server";
    import { getCookie, getIntlayer, getLocale } from "intlayer";
    
    export const getLocaleServer = createServerFn().handler(async () => {
      const locale = await getLocale({
        // İstekten çerezi al (varsayılan: 'INTLAYER_LOCALE')
        getCookie: (name) => {
          const cookieString = getRequestHeader("cookie");
    
          return getCookie(name, cookieString);
        },
        // İstekten başlığı al (varsayılan: 'x-intlayer-locale')
        // Accept-Language anlaşması kullanılarak geri dönüş (fallback)
        getHeader: (name) => getRequestHeader(name),
      });
    
      // getIntlayer() ile alınan bazı içerikler
      const content = getIntlayer("app", locale);
    
      return { locale, content };
    });
    

    ---

15. 15

    Bulunamayan sayfaları yönetme

    Bir kullanıcı var olmayan bir sayfayı ziyaret ettiğinde, özel bir bulunamadı sayfası görüntüleyebilirsiniz ve yerel ayar öneki bulunamadı sayfasının tetiklenme şeklini etkileyebilir.

    TanStack Router'ın yerel ayar önekleriyle 404 işlemesini anlama

    TanStack Router'da, yerelleştirilmiş rotalarla 404 sayfalarını işlemek çok katmanlı bir yaklaşım gerektirir:

    1. Özel 404 rotası: 404 kullanıcı arabirimini görüntülemek için belirli bir rota
    2. Rota düzeyinde doğrulama: Yerel ayar öneklerini doğrular ve geçersiz olanları 404'e yönlendirir
    3. Catch-all rotası: Yerel ayar segmentindeki eşleşmeyen tüm yolları yakalar

    src/routes/{-$locale}/404.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createFileRoute } from "@tanstack/solid-router";
    
    // Bu, özel bir /[locale]/404 rotası oluşturur
    // Hem doğrudan bir rota olarak kullanılır hem de diğer dosyalarda bir bileşen olarak içe aktarılır
    export const Route = createFileRoute("/{-$locale}/404")({
      component: NotFoundComponent,
    });
    
    // notFoundComponent ve catch-all rotalarında yeniden kullanılabilmesi için ayrı olarak dışa aktarıldı
    export function NotFoundComponent() {
      return (
        <div>
          <h1>404</h1>
        </div>
      );
    }
    

    src/routes/{-$locale}/route.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createFileRoute, Outlet, redirect } from "@tanstack/solid-router";
    import { validatePrefix } from "intlayer";
    import { NotFoundComponent } from "./404";
    
    export const Route = createFileRoute("/{-$locale}")({
      // beforeLoad, rota işlenmeden (render) önce çalışır (hem sunucu hem istemci)
      // Yerel ayar önekini doğrulamak için ideal yerdir
      beforeLoad: ({ params }) => {
        const localeParam = params.locale;
    
        // validatePrefix, yerel ayarın intlayer yapılandırmanıza göre geçerli olup olmadığını kontrol eder
        const { isValid, localePrefix } = validatePrefix(localeParam);
    
        if (!isValid) {
          // Geçersiz yerel ayar öneki - geçerli bir yerel ayar önekiyle 404 sayfasına yönlendir
          throw redirect({
            to: "/{-$locale}/404",
            params: { locale: localePrefix },
          });
        }
      },
      component: Outlet,
      // notFoundComponent, bir alt rota mevcut olmadığında çağrılır
      // ör: /en/var-olmayan-sayfa /en düzeni içinde bunu tetikler
      notFoundComponent: NotFoundComponent,
    });
    

    src/routes/{-$locale}/$.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createFileRoute } from "@tanstack/solid-router";
    
    import { NotFoundComponent } from "./404";
    
    // $ (splat/catch-all) rotası, diğer rotalarla eşleşmeyen tüm yollarla eşleşir
    // ör: /en/derin/ic-ice/gecersiz/yol
    // Bu, bir yerel ayar içindeki TÜM eşleşmeyen yolların 404 sayfasını göstermesini sağlar
    // Bu olmadan, derin eşleşmeyen yollar boş bir sayfa veya hata gösterebilir
    export const Route = createFileRoute("/{-$locale}/$")({
      component: NotFoundComponent,
    });
    

16. 16

    Bileşenlerinizden içeriği çıkartı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 çıkartmak için bir derleyici / çıkartıcı önerir.

    Kurulumu yapmak 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 = {
      // ... Yapılandırmanızın geri kalanı
      compiler: {
        /**
         * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.
         */
        enabled: true,
    
        /**
         * Çıkış dosyaları yolunu tanımlar
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Dönüştürüldükten sonra bileşenlerin kaydedilip kaydedilmeyeceğini belirtir.
         *
         * - `true` ise, derleyici diskteki bileşen dosyasını yeniden yazacaktır. Böylece dönüşüm kalıcı olacak ve derleyici bir sonraki işlem için dönüşümü atlayacaktır. Bu şekilde, derleyici uygulamayı dönüştürebilir ve ardından kaldırılabilir.
         *
         * - `false` ise, derleyici `useIntlayer()` fonksiyon çağrısını yalnızca derleme çıktısındaki koda enjekte ederek temel kod tabanını olduğu gibi tutacaktır. Dönüşüm yalnızca bellekte yapılacaktır.
         */
        saveComponents: false,
    
        /**
         * Sözlük anahtarı öneki
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Extract komutuBabel derleyicisi

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

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    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 { intlayer, intlayerCompiler } from "vite-intlayer";
    import { defineConfig } from "vite";
    import { devtools } from "@tanstack/devtools-vite";
    import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
    import solidPlugin from "vite-plugin-solid";
    
    export default defineConfig({
      plugins: [
        devtools(),
        tanstackStart({
          router: {
            routeFileIgnorePattern:
              ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
          },
        }),
        solidPlugin({ ssr: true }),
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npm run build # veya npm run dev
    

    ---

17. 16

    Pre-render & Generate Sitemap

    Intlayer, uygulamanız için kolayca bir sitemap oluşturmanıza yardımcı olmak için yerleşik bir sitemap oluşturucusu ile gelir. Yerelleştirilmiş rotaları işler ve arama motorları için gerekli metaveriyi ekler.

    Intlayer tarafından oluşturulan sitemap, xhtml:link namespace'ini (Hreflang XML Extensions) destekler. Yalnızca ham URL'leri listeleyen varsayılan sitemap oluşturucularının aksine, Intlayer bir sayfanın tüm dil sürümleri arasında gerekli çift yönlü bağlantıları otomatik olarak oluşturur (örneğin, /about, /about?lang=fr ve /about?lang=es). Bu, arama motorlarının doğru dil sürümünü doğru kitleye dizine eklemesini ve sunmasını sağlar.

    Bunu kullanmak için, öncelikle vite.config.ts dosyanızı yerelleştirilmiş rotalarınız için ön işlemeyi etkinleştirmek ve varsayılan TanStack Start sitemap oluşturmasını devre dışı bırakmak üzere yapılandırmanız gerekir.

    vite.config.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { localeMap, localeFlatMap } from "intlayer";
    // ... diğer importlar
    
    export const pathList = ["", "/about", "/404"];
    
    const localizedPages = localeFlatMap(({ urlPrefix }) =>
      pathList.map((path) => ({
        path: `${urlPrefix}${path}`,
        prerender: {
          enabled: true,
        },
      }))
    );
    
    export default defineConfig({
      plugins: [
        // ... diğer pluginler
        tanstackStart({
          // ... diğer config
          sitemap: {
            enabled: false,
          },
          prerender: {
            enabled: true,
            crawlLinks: false,
            concurrency: 10,
          },
          pages: localizedPages,
        }),
      ],
    });
    

    Ardından, generateSitemap fonksiyonunu kullanan bir src/routes/sitemap[.]xml.ts route oluşturun:

    src/routes/sitemap[.]xml.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { createFileRoute } from "@tanstack/solid-router";
    import { generateSitemap } from "intlayer";
    
    const SITE_URL = "http://localhost:3000";
    
    export const Route = createFileRoute("/sitemap.xml")({
      server: {
        handlers: {
          GET: async () => {
            const sitemap = generateSitemap(
              [
                { path: "/", changefreq: "daily", priority: 1.0 },
                { path: "/about", changefreq: "monthly", priority: 0.8 },
              ],
              { siteUrl: SITE_URL }
            );
    
            return new Response(sitemap, {
              headers: { "Content-Type": "application/xml" },
            });
          },
        },
      },
    });
    

    ---

18. 17

    TypeScript'i Yapılandırın

    Intlayer, TypeScript'in avantajlarından yararlanmak ve kod tabanınızı daha güçlü hale getirmek için modül genişletme (module augmentation) kullanır.

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

    tsconfig.json

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    {
      // ... mevcut ayarlarınız
      include: [
        // ... mevcut içerikleriniz (includes)
        ".intlayer/**/*.ts", // Otomatik olarak oluşturulan türleri dahil edin
      ],
    }
    

    ---

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaların yoksayılması önerilir. Bu, bunları Git deponuza göndermenizi engeller.

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ükle

Bu uzantı şunları sunar:

• Çeviri anahtarları için Otomatik Tamamlama.
• Eksik çeviriler için Gerçek zamanlı hata tespiti.
• Ç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 ayrıntı için Intlayer VS Code Uzantısı dokümantasyonuna bakın.

Daha İleri Gitmek

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

Dokümantasyon Referansları

• Intlayer Dokümantasyonu
• Tanstack Start Dokümantasyonu
• useIntlayer hook'u
• useLocale hook'u
• İçerik Bildirimi
• Yapılandırma