@intlayer/docs 5.5.10 → 5.5.12

package/frequent_questions/ja/get_locale_cookie.md

@@ -0,0 +1,144 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: クッキー / ヘッダーからロケールを取得する方法
+description: クッキー / ヘッダーからロケールを取得する方法を学びます。
+keywords:
+  - クッキー
+  - ヘッダー
+  - intlayer
+  - ロケール
+  - フック
+  - useLocale
+  - useLocaleCookie
+  - next.js
+  - react-intlayer
+  - vue-intlayer
+slugs:
+  - doc
+  - faq
+  - get-locale-cookie
+---
+
+# クッキー / ヘッダーからロケールを取得する方法
+
+## フックの使用（推奨）
+
+ほとんどのユースケースでは、`useLocale` フックを使用して現在のロケールを取得することを推奨します。これは自動的に解決されます。Vue.js の `useLocale` コンポーザブルと同様に動作します。
+
+```ts
+import { useLocale } from "next-intlayer";
+// or import { useLocale } from "react-intlayer";
+// or import { useLocale } from "vue-intlayer";
+
+ts;
+// クライアントサイドでの使用例
+const { locale } = useLocale();
+```
+
+サーバーコンポーネントの場合は、以下からインポートできます:
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+クッキーの値のみを解決する `useLocaleCookie` フックもあります。
+
+## 手動でのクッキー設定
+
+カスタムクッキー名を次のように宣言できます。
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // デフォルトは 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+それを取得する方法は以下の通りです。
+
+### クライアントサイド
+
+```ts
+// デフォルトのクッキー名を使用する場合
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// カスタムクッキー名を使用する場合
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### サーバーサイド（Next.js）
+
+```ts
+import { cookies } from "next/headers";
+
+// デフォルトのクッキー名を使用する場合
+const locale = cookies().get("intlayer-locale")?.value;
+
+// カスタムクッキー名を使用する場合
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### localeがまだ設定されていない場合
+
+localeはユーザーが明示的にlocaleを選択したときにのみクッキーとして設定されます。デフォルトでは、新しい訪問者に対しては、localeはヘッダーのフィールドから解釈されます。
+
+ユーザーの優先するロケールはリクエストヘッダーから検出できます。以下はその処理例です：
+
+```ts
+/**
+ * リクエストヘッダーからロケールを検出する
+ *
+ * accept-language ヘッダーはロケール検出において最も重要です。
+ * これは言語コードと品質値（q値）のリストを含み、
+ * ユーザーの優先言語を優先順位順に示します。
+ *
+ * 例: "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US は第一優先言語（q=1.0が暗黙的に設定されている）
+ * - en は第二選択肢（q=0.9）
+ * - fr は第三選択肢（q=0.8）
+ * - es は第四選択肢（q=0.7）
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * ブラウザが通常送信するネゴシエーターヘッダーの例
+ * これらのヘッダーはユーザーの優先言語を判定するのに役立ちます
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// 使用例:
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/frequent_questions/ja/intlayer_command_undefined.md

@@ -0,0 +1,156 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Intlayer コマンドが未定義
+description: intlayer コマンド未定義エラーの修正方法を学びます。
+keywords:
+  - intlayer
+  - コマンド
+  - 未定義
+  - エラー
+  - vscode
+  - 拡張機能
+  - プラグイン
+  - フレームワーク
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - intlayer-command-undefined
+---
+
+# Intlayer コマンドが未定義
+
+## 概要
+
+Intlayer CLI は、辞書の構築や翻訳のプッシュなど、intlayer コンテンツを便利に管理する方法を提供します。しかし、プロジェクトの動作に必須ではありません。Next.js 向けの `withIntlayer()` や Vite 向けの `intlayerPlugin()` のようなバンドラープラグインを使用している場合、Intlayer はアプリのビルド時や開発サーバーの起動時に自動的に辞書を構築します。開発モードでは、変更を監視し、コンテンツ宣言ファイルを自動的に再構築します。
+
+intlayer コマンドには以下の方法でアクセスできます：
+
+- `intlayer` CLI コマンドを直接使用する
+- [VSCode 拡張機能](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/vs_code_extension.md) を使用する
+- `@intlayer/cli` SDK を使用する
+
+## 問題
+
+`intlayer` コマンドを使用しようとすると、次のエラーが発生することがあります：
+
+```bash
+'intlayer' は、内部コマンドまたは外部コマンド、操作可能なプログラムまたはバッチ ファイルとして認識されていません。
+```
+
+## 解決策
+
+以下の順番で解決策を試してください：
+
+1. **コマンドがインストールされているか確認する**
+
+```bash
+npx intlayer -h
+```
+
+期待される出力：
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            バージョン番号を出力
+    -h, --help               コマンドのヘルプを表示
+
+Commands:
+    dictionary|dictionaries  辞書操作
+    configuration|config     設定操作
+    help [command]           コマンドのヘルプを表示
+```
+
+2. **intlayer-cli パッケージをグローバルにインストールする**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> すでに `intlayer` パッケージをインストールしている場合は、これを行う必要はありません
+
+3. **パッケージをグローバルにインストールする**
+
+```bash
+npm install intlayer -g
+```
+
+4. **ターミナルを再起動する**  
+   新しいコマンドを認識させるために、ターミナルの再起動が必要な場合があります。
+
+5. **クリーンアップして再インストールする**  
+   上記の解決策がうまくいかない場合は：
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **インストールファイルを確認する**  
+   問題が解決しない場合は、以下のファイルが存在するか確認してください：
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` （`bin` フィールドが `./dist/cjs/cli.cjs` を参照している必要があります）
+
+7. **PATH 環境変数を確認する**  
+   npm のグローバル bin ディレクトリが PATH に含まれていることを確認してください：
+
+```bash
+# Unix系システム（macOS/Linux）の場合
+echo $PATH
+# /usr/local/bin や ~/.npm-global/bin のようなパスが含まれている必要があります
+
+# Windowsの場合
+echo %PATH%
+# npmのグローバルbinディレクトリが含まれている必要があります
+```
+
+8. **npxをフルパスで使用する**
+   コマンドがまだ見つからない場合は、npxをフルパスで試してください：
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **競合するインストールの確認**
+
+```bash
+# グローバルにインストールされているパッケージを一覧表示
+npm list -g --depth=0
+
+# 競合するグローバルインストールを削除
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# その後再インストール
+npm install -g intlayer
+```
+
+10. **Node.jsとnpmのバージョン確認**
+    互換性のあるバージョンを使用していることを確認してください：
+
+```bash
+node --version
+npm --version
+```
+
+    古いバージョンを使用している場合は、Node.jsとnpmのアップデートを検討してください。
+
+11. **権限の問題を確認する**  
+    権限エラーが発生している場合は、以下を試してください：
+
+```bash
+# Unix系システムの場合
+sudo npm install -g intlayer
+
+# または npm のデフォルトディレクトリを変更する
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+# ~/.profile または ~/.bashrc に以下を追加：
+export PATH=~/.npm-global/bin:$PATH
+```

package/frequent_questions/ja/locale_incorect_in_url.md

@@ -0,0 +1,74 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: URLから取得したロケールが誤っている
+description: URLから取得した誤ったロケールを修正する方法を学びます。
+keywords:
+  - ロケール
+  - URL
+  - intlayer
+  - next.js
+  - vite
+  - フレームワーク
+  - ミドルウェア
+  - 設定
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - locale-incorect-in-url
+---
+
+# URLから取得したロケールが誤っている
+
+## 問題の説明
+
+URLからロケールパラメータにアクセスしようとすると、ロケールの値が誤っている問題が発生することがあります：
+
+```js
+const { locale } = await params;
+console.log(locale); // 期待されるロケールの代わりに "about" を返します
+```
+
+## 解決策
+
+### 1. ファイル構造の確認
+
+Next.jsのアプリルーターのパスが以下の構造になっていることを確認してください：
+
+```bash
+src/app/[locale]/about/page.tsx
+```
+
+### 2. ミドルウェア設定の確認
+
+この問題は、ミドルウェアが存在しないか、トリガーされていない場合によく発生します。ミドルウェアファイルは以下の場所にある必要があります：
+
+```bash
+src/middleware.ts
+```
+
+このミドルウェアは、`prefixDefault` が `false` に設定されている場合にルートを書き換える役割を担っています。例えば、`/en/about` を `/about` に書き換えます。
+
+### 3. 設定に基づくURLパターン
+
+#### デフォルト設定（`prefixDefault: false`、`noPrefix: false`）
+
+- 英語: `/about`
+- フランス語: `/fr/about`
+- スペイン語: `/es/about`
+
+#### `prefixDefault: true` の場合
+
+- 英語: `/en/about`
+- フランス語: `/fr/about`
+- スペイン語: `/es/about`
+
+#### `noPrefix: true` の場合
+
+- 英語: `/about`
+- フランス語: `/about`
+- スペイン語: `/about`
+
+これらの設定オプションの詳細については、[設定ドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)を参照してください。

package/frequent_questions/ja/static_rendering.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Next.jsにおけるi18nの静的レンダリングと動的レンダリングの比較
+description: Next.jsでのi18nを用いた静的レンダリングと動的レンダリングの使い方を学びます。
+keywords:
+  - 静的
+  - 動的
+  - レンダリング
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - フレームワーク
+  - ミドルウェア
+  - 設定
+slugs:
+  - doc
+  - faq
+  - static-rendering
+---
+
+# Next.jsにおけるi18nの静的レンダリングと動的レンダリングの比較
+
+## **next-intl**に関する問題
+
+- **何が起こるのか？**
+  i18nルーティングされたアプリ（`/en/…`、`/fr/…`）のサーバーコンポーネント内で`useTranslations`、`getTranslations`、または任意のnext-intlヘルパーを使用すると、Next.jsはそのルート全体を**動的**としてマークします。([Next Intl][1])
+
+- **なぜか？**
+  next-intlは、リクエスト専用ヘッダー（`x-next-intl-locale`）から`headers()`を介して現在のロケールを取得します。`headers()`は**動的API**であるため、それに触れるコンポーネントは静的最適化を失います。([Next Intl][1], [Next.js][2])
+
+- **公式の回避策（ボイラープレート）**
+
+  1. サポートされているすべてのロケールで`generateStaticParams`をエクスポートします。
+  2. `useTranslations`を呼び出す**前に**、**すべての**レイアウト/ページで`setRequestLocale(locale)`を呼び出します。([Next Intl][1])
+     これによりヘッダー依存がなくなりますが、追加のコード管理が必要になり、本番環境で不安定なAPIとなります。
+
+## **intlayer**が問題を回避する方法
+
+**設計上の選択**
+
+1. **ルートパラメータのみ** – ロケールはNext.jsがすでに各ページに渡している`[locale]`のURLセグメントから取得されます。
+2. **コンパイル時バンドル** – 翻訳は通常のESモジュールとしてインポートされるため、ツリーシェイクされビルド時に埋め込まれます。
+3. **動的APIなし** – `useT()`は`headers()`や`cookies()`からではなく、Reactコンテキストから読み取ります。
+4. **追加設定不要** – ページが`app/[locale]/`配下にあると、Next.jsはロケールごとに1つのHTMLファイルを自動的にプリレンダリングします。

package/frequent_questions/ja/translated_path_url.md

@@ -0,0 +1,56 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: URLパスを翻訳できますか？
+description: URLパスの翻訳方法について学びます。
+keywords:
+  - 配列
+  - コンテンツ
+  - 宣言
+  - intlayer
+  - ミドルウェア
+  - プロキシ
+  - リライト
+  - プレフィックス
+  - ロケール
+  - URL
+slugs:
+  - doc
+  - faq
+  - translated-path-url
+---
+
+# 次のようにURLを翻訳することは可能ですか：
+
+```bash
+en -> /product （プレフィックスなし）または /en/product （プレフィックスあり）
+fr -> /fr/produit
+es -> /es/producto
+```
+
+残念ながらIntlayerでは指定されたようにURLを翻訳することはできません。これを実現するには、独自のミドルウェアやプロキシを使用してURLを書き換える必要があります。
+
+しかし、`getMultilingualUrl`関数を使って、特定のロケールに対してURLにプレフィックスを挿入することは可能です。
+
+```ts
+import { getMultilingualUrl, Locales } from "intlayer";
+
+const url = getMultilingualUrl("/product");
+
+/**
+ * en -> /product （プレフィックスなし）または /en/product （プレフィックスあり）
+ * fr -> /fr/product
+ * es -> /es/product
+ */
+console.log(url);
+```
+
+または `getLocalizedUrl`
+
+```ts
+import { getLocalizedUrl, Locales } from "intlayer";
+
+const url = getLocalizedUrl("/product", Locales.FRENCH);
+
+console.log(url); // /fr/product
+```

package/frequent_questions/ja/unknown_command.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: 不明なコマンド
+description: 不明なコマンドエラーの修正方法を学ぶ。
+keywords:
+  - 不明
+  - コマンド
+  - エラー
+  - intlayer
+  - fill
+  - build
+  - verbose
+  - ターミナル
+  - 再起動
+  - ローカル
+slugs:
+  - doc
+  - faq
+  - unknown-command
+---
+
+# エラー: 不明なコマンド fill / build / その他
+
+`npx intlayer fill --verbose` を実行して以下のように表示される場合：
+
+```
+error: unknown command 'fill'
+```
+
+しかし `fill` コマンドが _存在するはず_ だと確信している場合、以下の手順で解決してください：
+
+## 1. **最新バージョンを使用していることを確認する**
+
+以下を実行します：
+
+```bash
+npx intlayer --version                  # 現在のローカルの intlayer バージョン
+npx intlayer@latest --version           # 現在の最新 intlayer バージョン
+```
+
+これにより `npx` は最新バージョンを取得します。次に再度試してください：
+
+```bash
+npx intlayer@latest build --verbose
+```
+
+## 2. **コマンドが登録されているか確認する**
+
+以下で確認できます：
+
+```bash
+npx intlayer --help                     # コマンドに関する情報を提供
+```
+
+コマンド一覧に該当のコマンドが表示されるか確認してください。
+
+リポジトリに移動し、コマンドがエクスポートされてCLIのエントリーポイントに登録されていることを確認してください。Intlayerは `commander` フレームワークを使用しています。
+
+CLIに関するコード：
+https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/cli/src/cli.ts
+
+## 4. **ターミナルを再起動する**
+
+新しいコマンドを認識させるために、ターミナルの再起動が必要な場合があります。
+
+## 5. **`intlayer` を開発している場合は再ビルドしてリンクする**
+
+ローカルで `intlayer` を開発している場合：
+
+```bash
+# intlayer ディレクトリ内で
+npm install
+npm run build
+npm link
+```
+
+別のターミナルで：
+
+```bash
+intlayer fill --verbose
+```
+
+これは、あなたが作業しているローカルバージョンを使用します。
+
+## 6. **npx キャッシュをクリアする（古いバージョンに固まっている場合）**
+
+```bash
+npx clear-npx-cache
+```
+
+または、キャッシュされた intlayer パッケージを手動で削除します：
+
+```bash
+rm -rf ~/.npm/_npx
+```
+
+pnpm、yarn、bun、または他のパッケージマネージャーを使用している場合は、それに相当する方法を確認してください。

package/frequent_questions/ko/SSR_Next_no_[locale].md

@@ -0,0 +1,105 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: 페이지 경로에 `[locale]` 없이 Next.js에서 Intlayer를 사용할 수 있나요?
+description: 페이지 경로에 `[locale]` 없이 Next.js에서 Intlayer를 사용하는 방법을 알아보세요.
+keywords:
+  - locale
+  - 경로
+  - intlayer
+  - next.js
+  - vite
+  - 프레임워크
+  - 미들웨어
+  - 구성
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - ssr-next-no-[locale]
+---
+
+# 페이지 경로에 `[locale]` 없이 Next.js에서 Intlayer를 사용할 수 있나요?
+
+네, 페이지 경로에 `[locale]` 없이 Next.js에서 Intlayer를 사용하는 것이 가능합니다. 하지만 페이지를 분리하는 것이 검색 엔진에서 더 많은 키워드를 유발할 수 있기 때문에 권장하지 않습니다. 또한 SSR에도 영향을 미칠 수 있습니다.
+
+원하신다면, [Intlayer with Next.js](https://intlayer.org/doc/environment/nextjs) 가이드에 설명된 동일한 단계를 따르세요,
+
+- `src/middleware.ts` 없음
+- `generateStaticParams` 없음
+
+```tsx fileName="src/app/layout.tsx"
+import type { FC, PropsWithChildren } from "react";
+
+const LocaleLayout: FC<PropsWithChildren> = ({ children }) => (
+  <html lang={undefined} dir={undefined}>
+    <body className={inter.className}>{children}</body>
+  </html>
+);
+
+export default LocaleLayout;
+```
+
+```tsx fileName="src/app/page.tsx"
+import type { FC } from "react";
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { PageContent } from "@components/pageContent";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC = () => {
+  return (
+    <IntlayerServerProvider>
+      <PageContent />
+      <ServerComponentExample />
+
+      <IntlayerClientProvider>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+
+export default Page;
+```
+
+```tsx fileName="src/component/pageContent.ts"
+"use client";
+
+import { type FC } from "react";
+import { useIntlayer } from "next-intlayer";
+import { useHTMLLanguage } from "@hooks/htmlTextDir";
+
+const PageContent: FC = () => {
+  useHTMLLanguage();
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/hooks/htmlTextDir.ts"
+"use client";
+
+import { useEffect } from "react";
+import { getHTMLTextDir } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const useHTMLLanguage = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    if (!document) return;
+
+    document.documentElement.lang = locale; // 문서의 언어 설정
+    document.documentElement.dir = getHTMLTextDir(locale); // 문서의 텍스트 방향 설정
+  }, [locale]);
+};
+```