@intlayer/docs 5.7.4 → 5.7.6-canary.0

package/docs/ko/dictionary/enumeration.md

@@ -15,8 +15,6 @@ slugs:
   - doc
   - concept
   - content
-  - ko
-  - dictionary
   - enumeration
 ---
 

package/docs/ko/packages/react-intlayer/useI18n.md

@@ -0,0 +1,250 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: useI18n 훅 문서 | react-intlayer
+description: react-intlayer 패키지에서 useI18n 훅을 사용하는 방법을 알아보세요
+keywords:
+  - useI18n
+  - i18n
+  - 번역
+  - 사전
+  - Intlayer
+  - 국제화
+  - 문서
+  - Next.js
+  - 자바스크립트
+  - 리액트
+slugs:
+  - doc
+  - packages
+  - react-intlayer
+  - useI18n
+---
+
+# React 통합: `useI18n` 훅 문서
+
+이 섹션에서는 React 애플리케이션 내에서 `useI18n` 훅을 사용하는 방법에 대해 자세히 안내하며, 효율적인 콘텐츠 현지화를 가능하게 합니다.
+
+## React에서 `useI18n` 가져오기
+
+`useI18n` 훅은 다음과 같이 상황에 맞게 React 애플리케이션에 가져와 통합할 수 있습니다:
+
+- **클라이언트 컴포넌트:**
+
+  ```typescript codeFormat="typescript"
+  import { useI18n } from "react-intlayer"; // 클라이언트 측 React 컴포넌트에서 사용
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useI18n } from "react-intlayer"; // 클라이언트 측 React 컴포넌트에서 사용
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useI18n } = require("react-intlayer"); // 클라이언트 측 React 컴포넌트에서 사용
+  ```
+
+- **서버 컴포넌트:**
+
+  ```typescript codeFormat="commonjs"
+  import { useI18n } from "react-intlayer/server"; // 서버 측 React 컴포넌트에서 사용
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useI18n } from "react-intlayer/server"; // 서버 측 React 컴포넌트에서 사용
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useI18n } = require("react-intlayer/server"); // 서버 측 React 컴포넌트에서 사용
+  ```
+
+## 매개변수
+
+이 훅은 두 개의 매개변수를 받습니다:
+
+1. **`namespace`**: 번역 키의 범위를 지정하는 사전 네임스페이스입니다.
+2. **`locale`** (선택 사항): 원하는 로케일입니다. 지정하지 않으면 컨텍스트의 로케일이 기본값으로 사용됩니다.
+
+## 사전
+
+모든 사전 키는 타입 안전성을 높이고 오류를 방지하기 위해 콘텐츠 선언 파일 내에 선언되어야 합니다. [설정 지침은 여기에서 확인할 수 있습니다](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/get_started.md).
+
+## React에서의 사용 예시
+
+React 컴포넌트 내에서 `useI18n` 훅을 사용하는 예시:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { useI18n, IntlayerServerProvider } from "react.intlayer/server";
+import { Locales } from "intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.jsx" codeFormat="esm"
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { IntlayerServerProvider, useI18n } from "react-intlayer/server";
+
+const App = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.cjs" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+const { IntlayerServerProvider, useI18n } = require("react-intlayer/server");
+
+const App = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useI18n } from "react-intlayer";
+
+const ComponentExample: FC = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 제목을 표시합니다 */}
+      <p>{t("description")}</p> {/* 설명을 표시합니다 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.jsx" codeFormat="esm"
+import { useI18n } from "react-intlayer";
+
+const ComponentExample = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 제목을 표시합니다 */}
+      <p>{t("description")}</p> {/* 설명을 표시합니다 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.cjs" codeFormat="commonjs"
+const { useI18n } = require("react-intlayer");
+
+const ComponentExample = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 제목을 표시합니다 */}
+      <p>{t("description")}</p> {/* 설명을 표시합니다 */}
+    </div>
+  );
+};
+```
+
+```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat="typescript"
+import { useI18n } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 제목을 표시합니다 */}
+      <p>{t("description")}</p> {/* 설명을 표시합니다 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.jsx" codeFormat="esm"
+import { useI18n } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 제목을 표시합니다 */}
+      <p>{t("description")}</p> {/* 설명을 표시합니다 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.cjs" codeFormat="commonjs"
+const { useI18n } = require("react-intlayer/server");
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1>
+      <p>{t("description")}</p>
+    </div>
+  );
+};
+```
+
+## 속성 처리
+
+속성을 현지화할 때는 번역 값을 적절히 접근해야 합니다:
+
+```jsx
+<!-- 접근성 속성(예: aria-label)의 경우, 순수 문자열이 필요하므로 .value를 사용하세요 -->
+<button aria-label={t("button.ariaLabel").value}>{t("button.text")}</button>
+```
+
+## 추가 자료
+
+- **Intlayer 비주얼 에디터**: 보다 직관적인 콘텐츠 관리 경험을 위해 비주얼 에디터 문서를 [여기](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)에서 참고하세요.
+
+이 섹션은 React 애플리케이션에서 `useI18n` 훅의 통합을 구체적으로 다루며, 현지화 과정을 단순화하고 다양한 로케일 간 콘텐츠 일관성을 보장합니다.
+
+## 문서 기록
+
+- 6.0.0 - 2025-06-29: `useI18n` 훅 문서 초안 작성

package/docs/pt/configuration.md

@@ -270,10 +270,12 @@ Configurações que controlam o comportamento do middleware, incluindo como a ap
 - **prefixDefault**:
 
   - _Tipo_: `boolean`
-  - _Padrão_: `true`
+  - _Padrão_: `false`
   - _Descrição_: Indica se o idioma padrão deve ser incluído na URL.
-  - _Exemplo_: `false`
-  - _Nota_: Se `false`, as URLs para o idioma padrão não terão um prefixo de idioma.
+  - _Exemplo_: `true`
+  - _Nota_:
+    - Se `true` e `defaultLocale = 'en'`: path = `/en/dashboard` ou `/fr/dashboard`
+    - Se `false` e `defaultLocale = 'en'`: path = `/dashboard` ou `/fr/dashboard`
 
 - **basePath**:
 
@@ -281,7 +283,11 @@ Configurações que controlam o comportamento do middleware, incluindo como a ap
   - _Padrão_: `''`
   - _Descrição_: O caminho base para as URLs da aplicação.
   - _Exemplo_: `'/my-app'`
-  - _Nota_: Isso afeta como as URLs são construídas para a aplicação.
+  - _Nota_:
+    - Se a aplicação está hospedada em `https://example.com/my-app`
+    - O caminho base é `'/my-app'`
+    - A URL será `https://example.com/my-app/en`
+    - Se o caminho base não estiver definido, a URL será `https://example.com/en`
 
 - **serverSetCookie**:
 
@@ -293,11 +299,42 @@ Configurações que controlam o comportamento do middleware, incluindo como a ap
   - _Nota_: Controla se o cookie de idioma é definido em todas as requisições ou nunca.
 
 - **noPrefix**:
+
   - _Tipo_: `boolean`
   - _Padrão_: `false`
   - _Descrição_: Indica se o prefixo de idioma deve ser omitido das URLs.
   - _Exemplo_: `true`
-  - _Nota_: Se `true`, as URLs não conterão informações de idioma.
+  - _Nota_:
+    - Se `true`: Sem prefixo na URL
+    - Se `false`: Prefixo na URL
+    - Exemplo com `basePath = '/my-app'`:
+      - Se `noPrefix = false`: A URL será `https://example.com/my-app/en`
+      - Se `noPrefix = true`: A URL será `https://example.com`
+
+- **detectLocaleOnPrefetchNoPrefix**:
+
+  - _Tipo_: `boolean`
+  - _Padrão_: `false`
+  - _Descrição_: Controla se a detecção de idioma ocorre durante as requisições de prefetch do Next.js.
+  - _Exemplo_: `true`
+  - _Nota_: Esta configuração afeta como o Next.js gerencia o prefetch de idioma:
+    - **Cenário de exemplo:**
+      - O idioma do navegador do usuário é `'fr'`
+      - A página atual é `/fr/about`
+      - O link faz prefetch de `/about`
+    - **Com `detectLocaleOnPrefetchNoPrefix: true`:**
+      - O prefetch detecta o idioma `'fr'` do navegador
+      - Redireciona o prefetch para `/fr/about`
+    - **Com `detectLocaleOnPrefetchNoPrefix: false` (padrão):**
+      - O prefetch usa o idioma padrão
+      - Redireciona o prefetch para `/en/about` (assumindo que `'en'` é o padrão)
+    - **Quando usar `true`:**
+      - Sua aplicação usa links internos não localizados (ex. `<a href="/about">`)
+      - Você quer comportamento consistente de detecção de idioma entre requisições normais e de prefetch
+    - **Quando usar `false` (padrão):**
+      - Sua aplicação usa links com prefixo de idioma (ex. `<a href="/fr/about">`)
+      - Você quer otimizar a performance do prefetch
+      - Você quer evitar loops de redirecionamento potenciais
 
 ---
 

package/docs/pt/packages/react-intlayer/useI18n.md

@@ -0,0 +1,250 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: Documentação do Hook useI18n | react-intlayer
+description: Aprenda como usar o hook useI18n no pacote react-intlayer
+keywords:
+  - useI18n
+  - i18n
+  - tradução
+  - dicionário
+  - Intlayer
+  - internacionalização
+  - documentação
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-intlayer
+  - useI18n
+---
+
+# Integração com React: Documentação do Hook `useI18n`
+
+Esta seção fornece orientações detalhadas sobre como usar o hook `useI18n` em aplicações React, permitindo uma localização eficiente de conteúdo.
+
+## Importando `useI18n` no React
+
+O hook `useI18n` pode ser importado e integrado em aplicações React conforme o contexto, da seguinte forma:
+
+- **Componentes Cliente:**
+
+  ```typescript codeFormat="typescript"
+  import { useI18n } from "react-intlayer"; // Use em componentes React do lado do cliente
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useI18n } from "react-intlayer"; // Use em componentes React do lado do cliente
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useI18n } = require("react-intlayer"); // Use em componentes React do lado do cliente
+  ```
+
+- **Componentes Servidor:**
+
+  ```typescript codeFormat="commonjs"
+  import { useI18n } from "react-intlayer/server"; // Use em componentes React do lado do servidor
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useI18n } from "react-intlayer/server"; // Use em componentes React do lado do servidor
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useI18n } = require("react-intlayer/server"); // Use em componentes React do lado do servidor
+  ```
+
+## Parâmetros
+
+Este hook aceita dois parâmetros:
+
+1. **`namespace`**: Um namespace de dicionário para delimitar as chaves de tradução.
+2. **`locale`** (opcional): O locale desejado. Se não especificado, o locale do contexto será usado como padrão.
+
+## Dicionário
+
+Todas as chaves do dicionário devem ser declaradas dentro dos arquivos de declaração de conteúdo para aumentar a segurança de tipos e evitar erros. [Instruções de configuração podem ser encontradas aqui](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/get_started.md).
+
+## Exemplos de Uso em React
+
+Exemplos de uso do hook `useI18n` dentro de componentes React:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { useI18n, IntlayerServerProvider } from "react-intlayer/server";
+import { Locales } from "intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.jsx" codeFormat="esm"
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { IntlayerServerProvider, useI18n } from "react-intlayer/server";
+
+const App = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.cjs" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+const { IntlayerServerProvider, useI18n } = require("react-intlayer/server");
+
+const App = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useI18n } from "react-intlayer";
+
+const ComponentExample: FC = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* Exibe o título */}
+      <p>{t("description")}</p> {/* Exibe a descrição */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.jsx" codeFormat="esm"
+import { useI18n } from "react-intlayer";
+
+const ComponentExample = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* Exibe o título */}
+      <p>{t("description")}</p> {/* Exibe a descrição */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.cjs" codeFormat="commonjs"
+const { useI18n } = require("react-intlayer");
+
+const ComponentExample = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* Exibe o título */}
+      <p>{t("description")}</p> {/* Exibe a descrição */}
+    </div>
+  );
+};
+```
+
+```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat="typescript"
+import { useI18n } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* Exibe o título */}
+      <p>{t("description")}</p> {/* Exibe a descrição */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.jsx" codeFormat="esm"
+import { useI18n } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* Exibe o título */}
+      <p>{t("description")}</p> {/* Exibe a descrição */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.cjs" codeFormat="commonjs"
+const { useI18n } = require("react-intlayer/server");
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1>
+      <p>{t("description")}</p>
+    </div>
+  );
+};
+```
+
+## Manipulação de Atributos
+
+Ao localizar atributos, acesse os valores de tradução de forma apropriada:
+
+```jsx
+<!-- Para atributos de acessibilidade (ex.: aria-label), use .value pois são necessárias strings puras -->
+<button aria-label={t("button.ariaLabel").value}>{t("button.text")}</button>
+```
+
+## Recursos Adicionais
+
+- **Editor Visual Intlayer**: Para uma experiência de gerenciamento de conteúdo mais intuitiva, consulte a documentação do editor visual [aqui](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md).
+
+Esta seção cobre especificamente a integração do hook `useI18n` em aplicações React, simplificando o processo de localização e garantindo a consistência do conteúdo entre diferentes locais.
+
+## Histórico da Documentação
+
+- 6.0.0 - 2025-06-29: Escrita inicial da documentação do hook `useI18n`

package/docs/ru/configuration.md

@@ -268,10 +268,12 @@ module.exports = config;
 - **prefixDefault**:
 
   - _Тип_: `boolean`
-  - _По умолчанию_: `true`
+  - _По умолчанию_: `false`
   - _Описание_: Включать ли локаль по умолчанию в URL.
-  - _Пример_: `false`
-  - _Примечание_: Если `false`, URL для локали по умолчанию не будут содержать префикс локали.
+  - _Пример_: `true`
+  - _Примечание_:
+    - Если `true` и `defaultLocale = 'en'`: path = `/en/dashboard` или `/fr/dashboard`
+    - Если `false` и `defaultLocale = 'en'`: path = `/dashboard` или `/fr/dashboard`
 
 - **basePath**:
 
@@ -279,7 +281,11 @@ module.exports = config;
   - _По умолчанию_: `''`
   - _Описание_: Базовый путь для URL приложения.
   - _Пример_: `'/my-app'`
-  - _Примечание_: Это влияет на то, как формируются URL для приложения.
+  - _Примечание_:
+    - Если приложение размещено на `https://example.com/my-app`
+    - Базовый путь `'/my-app'`
+    - URL будет `https://example.com/my-app/en`
+    - Если базовый путь не установлен, URL будет `https://example.com/en`
 
 - **serverSetCookie**:
 
@@ -291,11 +297,42 @@ module.exports = config;
   - _Примечание_: Управляет, устанавливается ли cookie локали при каждом запросе или никогда.
 
 - **noPrefix**:
+
   - _Тип_: `boolean`
   - _По умолчанию_: `false`
   - _Описание_: Исключать ли префикс локали из URL.
   - _Пример_: `true`
-  - _Примечание_: Если `true`, URL не будут содержать информацию о локали.
+  - _Примечание_:
+    - Если `true`: Без префикса в URL
+    - Если `false`: С префиксом в URL
+    - Пример с `basePath = '/my-app'`:
+      - Если `noPrefix = false`: URL будет `https://example.com/my-app/en`
+      - Если `noPrefix = true`: URL будет `https://example.com`
+
+- **detectLocaleOnPrefetchNoPrefix**:
+
+  - _Тип_: `boolean`
+  - _По умолчанию_: `false`
+  - _Описание_: Управляет, происходит ли обнаружение локали во время запросов предварительной загрузки Next.js.
+  - _Пример_: `true`
+  - _Примечание_: Эта настройка влияет на то, как Next.js обрабатывает предварительную загрузку локали:
+    - **Пример сценария:**
+      - Язык браузера пользователя `'fr'`
+      - Текущая страница `/fr/about`
+      - Ссылка предварительно загружает `/about`
+    - **С `detectLocaleOnPrefetchNoPrefix: true`:**
+      - Предварительная загрузка обнаруживает локаль `'fr'` из браузера
+      - Перенаправляет предварительную загрузку на `/fr/about`
+    - **С `detectLocaleOnPrefetchNoPrefix: false` (по умолчанию):**
+      - Предварительная загрузка использует локаль по умолчанию
+      - Перенаправляет предварительную загрузку на `/en/about` (предполагая, что `'en'` по умолчанию)
+    - **Когда использовать `true`:**
+      - Ваше приложение использует нелокализованные внутренние ссылки (например, `<a href="/about">`)
+      - Вы хотите согласованное поведение обнаружения локали между обычными и предварительными запросами
+    - **Когда использовать `false` (по умолчанию):**
+      - Ваше приложение использует ссылки с префиксом локали (например, `<a href="/fr/about">`)
+      - Вы хотите оптимизировать производительность предварительной загрузки
+      - Вы хотите избежать потенциальных циклов перенаправления
 
 ---
 

package/docs/ru/dictionary/enumeration.md

@@ -15,8 +15,6 @@ slugs:
   - doc
   - concept
   - content
-  - ru
-  - dictionary
   - enumeration
 ---