@intlayer/docs 5.5.10 → 5.5.12

package/frequent_questions/ko/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:
+  - 문서
+  - FAQ
+  - intlayer-명령어-정의되지-않음
+---
+
+# Intlayer 명령어 정의되지 않음
+
+## 개요
+
+Intlayer CLI는 사전 구축, 번역 푸시 등 intlayer 콘텐츠를 편리하게 제어할 수 있는 방법을 제공합니다. 그러나 프로젝트가 작동하는 데 필수적인 것은 아닙니다. 만약 Next.js용 `withIntlayer()`나 Vite용 `intlayerPlugin()`과 같은 번들러 플러그인을 사용하고 있다면, Intlayer는 앱 빌드 또는 개발 서버 시작 시 자동으로 사전을 빌드합니다. 개발 모드에서는 변경 사항을 감지하여 콘텐츠 선언 파일을 자동으로 재빌드하기도 합니다.
+
+intlayer 명령어에 접근하는 방법은 다음과 같습니다:
+
+- `intlayer` CLI 명령어를 직접 사용하는 방법
+- [VSCode 확장](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/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
+# 유닉스 기반 시스템용
+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/ko/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/ko/configuration.md)를 참조하세요.

package/frequent_questions/ko/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가 로케일별로 하나의 HTML 파일을 자동으로 사전 렌더링합니다.

package/frequent_questions/ko/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을 재작성해야 합니다.
+
+하지만 특정 로케일에 대해 URL에 접두사를 삽입하려면 `getMultilingualUrl` 함수를 사용할 수 있습니다.
+
+```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/ko/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/pt/SSR_Next_no_[locale].md

@@ -0,0 +1,105 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: É possível usar o Intlayer com Next.js sem `[locale]` no caminho da página?
+description: Aprenda como usar o Intlayer com Next.js sem `[locale]` no caminho da página.
+keywords:
+  - locale
+  - caminho
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configuração
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - ssr-next-no-[locale]
+---
+
+# É possível usar o Intlayer com Next.js sem `[locale]` no caminho da página?
+
+Sim, é possível usar o Intlayer com Next.js sem `[locale]` no caminho da página. No entanto, não é recomendado fazer isso, pois dividir sua página permite ativar mais palavras-chave nos motores de busca. Seu SSR também pode ser impactado.
+
+Se você quiser fazer isso, siga os mesmos passos descritos no guia [Intlayer com Next.js](https://intlayer.org/doc/environment/nextjs),
+
+- sem `src/middleware.ts`
+- sem `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]);
+};
+```

package/frequent_questions/pt/array_as_content_declaration.md

@@ -0,0 +1,72 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Posso usar um array como declaração de conteúdo?
+description: Aprenda como usar um array como declaração de conteúdo.
+keywords:
+  - array
+  - conteúdo
+  - declaração
+  - intlayer
+slugs:
+  - doc
+  - faq
+  - array-como-declaracao-de-conteudo
+---
+
+# Posso usar um array como declaração de conteúdo?
+
+Sim, você pode usar um array como declaração de conteúdo.
+
+```ts
+import { t, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  content: {
+    test: t({
+      en: ["Test", "Test2", "Test3"],
+      fr: ["Test", "Test2", "Test3"],
+      es: ["Test", "Test2", "Test3"],
+    }),
+  },
+};
+
+export default exampleContent;
+```
+
+Então você pode usar o conteúdo assim:
+
+```tsx
+import { useIntlayer } from "react-intlayer";
+
+const Example = () => {
+  const content = useIntlayer("example");
+
+  return (
+    <div>
+      {content.test.map((item) => (
+        <div key={item.value}>{item}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+```vue
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const content = useIntlayer("example");
+</script>
+
+<template>
+  <div>
+    <div v-for="item in content.test" :key="item.value">
+      {{ item }}
+    </div>
+  </div>
+</template>
+```
+
+`.value` permite obter o valor do conteúdo, não envolvido por um `IntlayerNode`.

package/frequent_questions/pt/build_dictionaries.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Como construir dicionários?
+description: Aprenda como construir dicionários.
+keywords:
+  - construir
+  - dicionários
+  - intlayer
+  - comando
+  - watch
+  - vscode
+  - plugin
+  - framework
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - construir-dicionarios
+---
+
+# Construir Dicionários
+
+## Como Construir Dicionários
+
+O Intlayer fornece uma ferramenta de linha de comando para construir dicionários.
+
+```bash
+npx intlayer dictionaries build
+```
+
+Este comando:
+
+- Escaneia todos os arquivos de declaração de conteúdo (`.content.{ts,tsx,js,mjs,cjs,json,...}`) no seu projeto.
+- Gera dicionários e os armazena na pasta `.intlayer/dictionary`.
+
+### Modo Watch
+
+Se você quiser atualizar automaticamente os dicionários quando alterações forem feitas nos arquivos de declaração de conteúdo, execute o seguinte comando:
+
+```bash
+npx intlayer dictionaries build --watch
+```
+
+Neste modo, o Intlayer irá escanear e construir os dicionários sempre que alterações forem feitas nos arquivos de declaração de conteúdo e atualizará automaticamente a pasta `.intlayer/dictionary`.
+
+### Usando a extensão do VSCode
+
+Você também pode usar a [extensão Intlayer para VSCode](https://github.com/aymericzip/intlayer/tree/main/docs/pt/vs_code_extension.md) para melhorar sua experiência com o Intlayer no VSCode.
+
+### Usando o plugin para seu framework de aplicação favorito
+
+Se você estiver usando um framework como Next.js (Webpack / Turbopack), Vite, React Native, Lynx etc., o Intlayer fornece um plugin que você pode usar para integrar o Intlayer em sua aplicação.
+
+O Intlayer irá construir os dicionários antes da compilação da sua aplicação.
+Da mesma forma, no modo de desenvolvimento, o Intlayer irá monitorar as alterações nos seus arquivos de declaração de conteúdo e reconstruir os dicionários automaticamente.
+
+Portanto, consulte a documentação específica do seu framework para aprender como integrar o plugin.