npm - @intlayer/docs - Versions diffs - 6.1.5 → 6.1.6-canary.0 - Mend

@intlayer/docs 6.1.5 → 6.1.6-canary.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/blog/ar/next-i18next_vs_next-intl_vs_intlayer.md +404 -173
package/blog/de/next-i18next_vs_next-intl_vs_intlayer.md +262 -113
package/blog/en/intlayer_with_next-i18next.mdx +431 -0
package/blog/en/intlayer_with_next-intl.mdx +335 -0
package/blog/en/next-i18next_vs_next-intl_vs_intlayer.md +403 -140
package/blog/en-GB/next-i18next_vs_next-intl_vs_intlayer.md +38 -28
package/blog/es/next-i18next_vs_next-intl_vs_intlayer.md +185 -71
package/blog/fr/next-i18next_vs_next-intl_vs_intlayer.md +38 -28
package/blog/it/next-i18next_vs_next-intl_vs_intlayer.md +38 -28
package/blog/ja/next-i18next_vs_next-intl_vs_intlayer.md +38 -28
package/blog/ko/next-i18next_vs_next-intl_vs_intlayer.md +38 -28
package/blog/pt/next-i18next_vs_next-intl_vs_intlayer.md +38 -28
package/blog/ru/next-i18next_vs_next-intl_vs_intlayer.md +36 -28
package/blog/tr/next-i18next_vs_next-intl_vs_intlayer.md +2 -0
package/blog/zh/next-i18next_vs_next-intl_vs_intlayer.md +38 -28
package/dist/cjs/generated/docs.entry.cjs +16 -0
package/dist/cjs/generated/docs.entry.cjs.map +1 -1
package/dist/esm/generated/docs.entry.mjs +16 -0
package/dist/esm/generated/docs.entry.mjs.map +1 -1
package/dist/types/generated/docs.entry.d.ts +1 -0
package/dist/types/generated/docs.entry.d.ts.map +1 -1
package/docs/ar/component_i18n.md +186 -0
package/docs/ar/vs_code_extension.md +48 -109
package/docs/de/component_i18n.md +186 -0
package/docs/de/vs_code_extension.md +46 -107
package/docs/en/component_i18n.md +186 -0
package/docs/en/intlayer_with_nextjs_14.md +18 -1
package/docs/en/intlayer_with_nextjs_15.md +18 -1
package/docs/en/vs_code_extension.md +24 -114
package/docs/en-GB/component_i18n.md +186 -0
package/docs/en-GB/vs_code_extension.md +42 -103
package/docs/es/component_i18n.md +182 -0
package/docs/es/vs_code_extension.md +53 -114
package/docs/fr/component_i18n.md +186 -0
package/docs/fr/vs_code_extension.md +50 -111
package/docs/hi/component_i18n.md +186 -0
package/docs/hi/vs_code_extension.md +49 -110
package/docs/it/component_i18n.md +186 -0
package/docs/it/vs_code_extension.md +50 -111
package/docs/ja/component_i18n.md +186 -0
package/docs/ja/vs_code_extension.md +50 -111
package/docs/ko/component_i18n.md +186 -0
package/docs/ko/vs_code_extension.md +48 -109
package/docs/pt/component_i18n.md +186 -0
package/docs/pt/vs_code_extension.md +46 -107
package/docs/ru/component_i18n.md +186 -0
package/docs/ru/vs_code_extension.md +48 -109
package/docs/tr/component_i18n.md +186 -0
package/docs/tr/vs_code_extension.md +54 -115
package/docs/zh/component_i18n.md +186 -0
package/docs/zh/vs_code_extension.md +51 -105
package/package.json +11 -11
package/src/generated/docs.entry.ts +16 -0

package/blog/en/intlayer_with_next-i18next.mdx ADDED Viewed

@@ -0,0 +1,431 @@
+```bash
+.
+├── i18n.config.ts
+└── src
+    ├── locales
+    │   ├── en
+    │   │  ├── common.json
+    │   │  └── about.json
+    │   └── fr
+    │      ├── common.json
+    │      └── about.json
+    ├── app
+    │   ├── i18n
+    │   │   └── server.ts
+    │   └── [locale]
+    │       ├── layout.tsx
+    │       └── about.tsx
+    └── components
+        ├── I18nProvider.tsx
+        ├── ClientComponent.tsx
+        └── ServerComponent.tsx
+```
+```ts fileName="i18n.config.ts"
+export const locales = ['en', 'fr'] as const;
+export type Locale = (typeof locales)[number];
+export const defaultLocale: Locale = 'en';
+export const rtlLocales = ['ar', 'he', 'fa', 'ur'] as const;
+export const isRtl = (locale: string) =>
+  (rtlLocales as readonly string[]).includes(locale);
+export function localizedPath(locale: string, path: string) {
+  return locale === defaultLocale ? path : '/' + locale + path;
+}
+const ORIGIN = 'https://example.com';
+export function abs(locale: string, path: string) {
+  return ORIGIN + localizedPath(locale, path);
+}
+```
+```ts fileName="src/app/i18n/server.ts"
+import { createInstance } from 'i18next';
+import { initReactI18next } from 'react-i18next/initReactI18next';
+import resourcesToBackend from 'i18next-resources-to-backend';
+import { defaultLocale } from '@/i18n.config';
+// Load JSON resources from src/locales/<locale>/<namespace>.json
+const backend = resourcesToBackend(
+  (locale: string, namespace: string) =>
+    import(`../../locales/${locale}/${namespace}.json`)
+);
+export async function initI18next(
+  locale: string,
+  namespaces: string[] = ['common']
+) {
+  const i18n = createInstance();
+  await i18n
+    .use(initReactI18next)
+    .use(backend)
+    .init({
+      lng: locale,
+      fallbackLng: defaultLocale,
+      ns: namespaces,
+      defaultNS: 'common',
+      interpolation: { escapeValue: false },
+      react: { useSuspense: false },
+    });
+  return i18n;
+}
+```
+```tsx fileName="src/components/I18nProvider.tsx"
+'use client';
+import * as React from 'react';
+import { I18nextProvider } from 'react-i18next';
+import { createInstance } from 'i18next';
+import { initReactI18next } from 'react-i18next/initReactI18next';
+import resourcesToBackend from 'i18next-resources-to-backend';
+import { defaultLocale } from '@/i18n.config';
+const backend = resourcesToBackend(
+  (locale: string, namespace: string) =>
+    import(`../../locales/${locale}/${namespace}.json`)
+);
+type Props = {
+  locale: string;
+  namespaces?: string[];
+  resources?: Record<string, any>; // { ns: bundle }
+  children: React.ReactNode;
+};
+export default function I18nProvider({
+  locale,
+  namespaces = ['common'],
+  resources,
+  children,
+}: Props) {
+  const [i18n] = React.useState(() => {
+    const i = createInstance();
+    i.use(initReactI18next)
+      .use(backend)
+      .init({
+        lng: locale,
+        fallbackLng: defaultLocale,
+        ns: namespaces,
+        resources: resources ? { [locale]: resources } : undefined,
+        defaultNS: 'common',
+        interpolation: { escapeValue: false },
+        react: { useSuspense: false },
+      });
+    return i;
+  });
+  return <I18nextProvider i18n={i18n}>{children}</I18nextProvider>;
+}
+```
+```tsx fileName="src/app/[locale]/layout.tsx"
+import type { ReactNode } from 'react';
+import { locales, defaultLocale, isRtl, type Locale } from '@/i18n.config';
+export const dynamicParams = false;
+export function generateStaticParams() {
+  return locales.map((locale) => ({ locale }));
+}
+export default function LocaleLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: { locale: string };
+}) {
+  const locale: Locale = (locales as readonly string[]).includes(params.locale)
+    ? (params.locale as any)
+    : defaultLocale;
+  const dir = isRtl(locale) ? 'rtl' : 'ltr';
+  return (
+    <html lang={locale} dir={dir}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+```tsx fileName="src/app/[locale]/about.tsx"
+import I18nProvider from '@/components/I18nProvider';
+import { initI18next } from '@/app/i18n/server';
+import type { Locale } from '@/i18n.config';
+import ClientComponent from '@/components/ClientComponent';
+import ServerComponent from '@/components/ServerComponent';
+// Force static rendering for the page
+export const dynamic = 'force-static';
+export default async function AboutPage({
+  params: { locale },
+}: {
+  params: { locale: Locale };
+}) {
+  const namespaces = ['common', 'about'] as const;
+  const i18n = await initI18next(locale, [...namespaces]);
+  const tAbout = i18n.getFixedT(locale, 'about');
+  return (
+    <I18nProvider locale={locale} namespaces={[...namespaces]}>
+      <main>
+        <h1>{tAbout('title')}</h1>
+        <ClientComponent />
+        <ServerComponent t={tAbout} locale={locale} count={0} />
+      </main>
+    </I18nProvider>
+  );
+}
+```
+**Translations (one JSON per namespace under `src/locales/...`)**
+```json fileName="src/locales/en/about.json"
+{
+  "title": "About",
+  "description": "About page description",
+  "counter": {
+    "label": "Counter",
+    "increment": "Increment"
+  }
+}
+```
+```json fileName="src/locales/fr/about.json"
+{
+  "title": "À propos",
+  "description": "Description de la page À propos",
+  "counter": {
+    "label": "Compteur",
+    "increment": "Incrémenter"
+  }
+}
+```
+**Client component (loads only the required namespace)**
+```tsx fileName="src/components/ClientComponent.tsx"
+'use client';
+import React, { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+const ClientComponent = () => {
+  const { t, i18n } = useTranslation('about');
+  const [count, setCount] = useState(0);
+  const numberFormat = new Intl.NumberFormat(i18n.language);
+  return (
+    <div>
+      <p>{numberFormat.format(count)}</p>
+      <button
+        aria-label={t('counter.label')}
+        onClick={() => setCount((c) => c + 1)}
+      >
+        {t('counter.increment')}
+      </button>
+    </div>
+  );
+};
+export default ClientComponent;
+```
+> Ensure the page/provider includes only the namespaces you need (e.g. `about`).
+> If you use React < 19, memoize heavy formatters like `Intl.NumberFormat`.
+---
+### Usage in a sync server component
+This server component can be inserted under a client component. Because it might be nested under a client boundary, it should be synchronous. Compute translations and locale-dependent formatting in the parent (or pass the `t` function) and provide data via props.
+```tsx fileName="src/components/ServerComponent.tsx"
+type ServerComponentProps = {
+  t: (key: string) => string;
+  locale: string;
+  count: number;
+};
+const ServerComponent = ({ t, locale, count }: ServerComponentProps) => {
+  const formatted = new Intl.NumberFormat(locale).format(count);
+  return (
+    <div>
+      <p>{formatted}</p>
+      <button aria-label={t('counter.label')}>{t('counter.increment')}</button>
+    </div>
+  );
+};
+export default ServerComponent;
+```
+### Metadata / Sitemap / Robots
+Translating content is great. But people usually forget that the main goal of internationalization is to make your website more visible to the world. I18n is an incredible lever to improve your website visibility.
+Here's a list of good practices regarding multilingual SEO.
+- set hreflang meta tags in the `<head>` tag
+  > It helps search engines to understand what languages are available on the page
+- list all pages translations in the sitemap.xml using `http://www.w3.org/1999/xhtml` XML schema
+  >
+- do not forget to exclude prefixed pages from the robots.txt (e.g. `/dashboard`, and `/fr/dashboard`, `/es/dashboard`)
+  >
+- use custom Link component to redirect to the most localized page (e.g. in french `<a href="/fr/about">A propos</a>` )
+  >
+Developers often forget to properly reference their pages across locales.
+```ts fileName="i18n.config.ts"
+export const locales = ['en', 'fr'] as const;
+export type Locale = (typeof locales)[number];
+export const defaultLocale: Locale = 'en';
+export const rtlLocales = ['ar', 'he', 'fa', 'ur'] as const;
+export const isRtl = (locale: string) =>
+  (rtlLocales as readonly string[]).includes(locale);
+export function localizedPath(locale: string, path: string) {
+  return locale === defaultLocale ? path : '/' + locale + path;
+}
+const ORIGIN = 'https://example.com';
+export function abs(locale: string, path: string) {
+  return ORIGIN + localizedPath(locale, path);
+}
+```
+```tsx fileName="src/app/[locale]/about/layout.tsx"
+import type { Metadata } from 'next';
+import { locales, defaultLocale, localizedPath } from '@/i18n.config';
+export async function generateMetadata({
+  params,
+}: {
+  params: { locale: string };
+}): Promise<Metadata> {
+  const { locale } = params;
+  // Import the correct JSON bundle from src/locales
+  const messages = (await import('@/locales/' + locale + '/about.json'))
+    .default;
+  const languages = Object.fromEntries(
+    locales.map((locale) => [locale, localizedPath(locale, '/about')])
+  );
+  return {
+    title: messages.title,
+    description: messages.description,
+    alternates: {
+      canonical: localizedPath(locale, '/about'),
+      languages: { ...languages, 'x-default': '/about' },
+    },
+  };
+}
+export default async function AboutPage() {
+  return <h1>About</h1>;
+}
+```
+```ts fileName="src/app/sitemap.ts"
+import type { MetadataRoute } from 'next';
+import { locales, defaultLocale, abs } from '@/i18n.config';
+export default function sitemap(): MetadataRoute.Sitemap {
+  const languages = Object.fromEntries(
+    locales.map((locale) => [locale, abs(locale, '/about')])
+  );
+  return [
+    {
+      url: abs(defaultLocale, '/about'),
+      lastModified: new Date(),
+      changeFrequency: 'monthly',
+      priority: 0.7,
+      alternates: { languages },
+    },
+  ];
+}
+```
+```ts fileName="src/app/robots.ts"
+import type { MetadataRoute } from 'next';
+import { locales, defaultLocale, localizedPath } from '@/i18n.config';
+const ORIGIN = 'https://example.com';
+const expandAllLocales = (path: string) => [
+  localizedPath(defaultLocale, path),
+  ...locales
+    .filter((locale) => locale !== defaultLocale)
+    .map((locale) => localizedPath(locale, path)),
+];
+export default function robots(): MetadataRoute.Robots {
+  const disallow = [
+    ...expandAllLocales('/dashboard'),
+    ...expandAllLocales('/admin'),
+  ];
+  return {
+    rules: { userAgent: '*', allow: ['/'], disallow },
+    host: ORIGIN,
+    sitemap: ORIGIN + '/sitemap.xml',
+  };
+}
+```
+---
+### Middleware for locale routing
+Add a middleware to handle locale detection and routing:
+```ts fileName="src/middleware.ts"
+import { NextResponse, type NextRequest } from 'next/server';
+import { defaultLocale, locales } from '@/i18n.config';
+const PUBLIC_FILE = /\.[^/]+$/; // exclude files with extensions
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+  if (
+    pathname.startsWith('/_next') ||
+    pathname.startsWith('/api') ||
+    pathname.startsWith('/static') ||
+    PUBLIC_FILE.test(pathname)
+  ) {
+    return;
+  }
+  const hasLocale = locales.some(
+    (locale) =>
+      pathname === '/' + locale || pathname.startsWith('/' + locale + '/')
+  );
+  if (!hasLocale) {
+    const locale = defaultLocale;
+    const url = request.nextUrl.clone();
+    url.pathname = '/' + locale + (pathname === '/' ? '' : pathname);
+    return NextResponse.redirect(url);
+  }
+}
+export const config = {
+  matcher: [
+    // Match all paths except the ones starting with these and files with an extension
+    '/((?!api|_next|static|.*\\..*).*)',
+  ],
+};
+```