@intlayer/docs 6.1.4 → 6.1.6-canary.0

package/docs/ko/vs_code_extension.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-03-17
-updatedAt: 2025-09-22
+updatedAt: 2025-09-30
 title: 공식 VS 코드 확장
-description: VS 코드에서 Intlayer 확장을 사용하여 개발 워크플로를 향상시키는 방법을 알아보세요. 현지화된 콘텐츠 간을 빠르게 탐색하고 사전을 효율적으로 관리할 수 있습니다.
+description: VS 코드에서 Intlayer 확장을 사용하여 개발 워크플로우를 향상시키는 방법을 알아보세요. 현지화된 콘텐츠 간 빠른 탐색과 사전 관리를 효율적으로 수행할 수 있습니다.
 keywords:
   - VS 코드 확장
   - Intlayer
@@ -23,161 +23,100 @@ slugs:
 
 [**Intlayer**](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)는 프로젝트에서 현지화된 콘텐츠 작업 시 개발자 경험을 향상시키기 위해 설계된 **Intlayer**의 공식 Visual Studio Code 확장입니다.
 
-![Intlayer VS 코드 확장](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+![Intlayer VS 코드 확장](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif?raw=true)
 
 확장 링크: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
 
 ## 기능
 
-### 즉시 탐색
+![사전 채우기](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
-**정의로 이동 지원** – `useIntlayer` 키에서 `⌘ + 클릭`(Mac) 또는 `Ctrl + 클릭`(Windows/Linux)을 사용하여 해당 콘텐츠 파일을 즉시 엽니다.  
-**원활한 통합** – **react-intlayer** 및 **next-intlayer** 프로젝트와 문제없이 작동합니다.  
-**다국어 지원** – 다양한 언어의 현지화된 콘텐츠를 지원합니다.  
-**VS 코드 통합** – VS 코드의 탐색 및 명령 팔레트와 원활하게 통합됩니다.
-
-### 사전 관리 명령어
-
-VS 코드에서 직접 콘텐츠 사전을 관리하세요:
-
-- **사전 빌드** – 프로젝트 구조를 기반으로 콘텐츠 파일을 생성합니다.
-- **사전 푸시** – 최신 사전 콘텐츠를 저장소에 업로드합니다.
-- **사전 풀** – 저장소에서 최신 사전 콘텐츠를 로컬 환경으로 동기화합니다.
+- **즉시 탐색** – `useIntlayer` 키를 클릭하면 올바른 콘텐츠 파일로 빠르게 이동합니다.
 - **사전 채우기** – 프로젝트의 콘텐츠로 사전을 채웁니다.
-- **사전 테스트** – 누락되었거나 불완전한 번역을 식별합니다.
-
-### 콘텐츠 선언 생성기
-
-다양한 형식으로 구조화된 사전 파일을 쉽게 생성할 수 있습니다:
 
-현재 컴포넌트 작업 중이라면 `.content.{ts,tsx,js,jsx,mjs,cjs,json}` 파일을 자동으로 생성합니다.
+![명령어 목록](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_list_commands.gif?raw=true)
 
-컴포넌트 예시:
+- **Intlayer 명령어에 쉽게 접근** – 콘텐츠 사전을 빌드, 푸시, 풀, 채우기, 테스트를 손쉽게 수행합니다.
 
-```tsx fileName="src/components/MyComponent/index.tsx"
-const MyComponent = () => {
-  const { myTranslatedContent } = useIntlayer("my-component");
+![콘텐츠 파일 생성](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_create_content_file.gif?raw=true)
 
-  return <span>{myTranslatedContent}</span>;
-};
-```
-
-TypeScript 형식으로 생성된 파일:
+- **콘텐츠 선언 생성기** – 다양한 형식(`.ts`, `.esm`, `.cjs`, `.json`)으로 사전 콘텐츠 파일을 생성합니다.
 
-```tsx fileName="src/components/MyComponent/index.content.ts"
-import { t, type Dictionary } from "intlayer";
+![사전 테스트](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_test_missing_dictionary.gif?raw=true)
 
-const componentContent = {
-  key: "my-component",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
+- **사전 테스트** – 누락된 번역이 있는지 사전을 테스트합니다.
 
-export default componentContent;
-```
+![사전 재구성](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_rebuild_dictionary.gif?raw=true)
 
-사용 가능한 형식:
+- **사전을 최신 상태로 유지** – 프로젝트의 최신 콘텐츠로 사전을 최신 상태로 유지합니다.
 
-- **TypeScript (`.ts`)**
-- **ES 모듈 (`.esm`)**
-- **CommonJS (`.cjs`)**
-- **JSON (`.json`)**
-
-### Intlayer 탭 (활동 표시줄)
+![Intlayer 탭 (활동 표시줄)](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_search_dictionary.gif?raw=true)
 
-VS Code 활동 표시줄에서 Intlayer 아이콘을 클릭하여 Intlayer 탭을 엽니다. 이 탭에는 두 가지 뷰가 포함되어 있습니다:
-
-- **검색(Search)**: 사전과 그 내용을 빠르게 필터링할 수 있는 실시간 검색 바입니다. 입력할 때마다 결과가 즉시 업데이트됩니다.
-- **사전(Dictionaries)**: 환경/프로젝트, 사전 키, 그리고 항목을 기여하는 파일들의 트리 뷰입니다. 다음 작업을 할 수 있습니다:
-  - 파일을 클릭하여 편집기에서 엽니다.
-  - 툴바를 사용하여 다음 작업을 실행합니다: 빌드(Build), 풀(Pull), 푸시(Push), 채우기(Fill), 새로고침(Refresh), 테스트(Test), 사전 파일 생성(Create Dictionary File).
-  - 항목별 작업을 위한 컨텍스트 메뉴를 사용합니다:
-    - 사전에서는: 풀(Pull) 또는 푸시(Push)
-    - 파일에서는: 사전 채우기(Fill Dictionary)
-  - 편집기를 전환할 때, 해당 파일이 사전에 속해 있으면 트리가 일치하는 파일을 표시합니다.
-
-## 설치
-
-**Intlayer**를 VS Code 마켓플레이스에서 직접 설치할 수 있습니다:
-
-1. **VS Code**를 엽니다.
-2. **확장 마켓플레이스**로 이동합니다.
-3. **"Intlayer"**를 검색합니다.
-4. **설치**를 클릭합니다.
+- **Intlayer 탭 (활동 표시줄)** – 전용 사이드 탭에서 도구 모음과 컨텍스트 작업(빌드, 풀, 푸시, 채우기, 새로 고침, 테스트, 파일 생성)과 함께 사전을 탐색하고 검색합니다.
 
 ## 사용법
 
 ### 빠른 탐색
 
 1. **react-intlayer**를 사용하는 프로젝트를 엽니다.
-2. `useIntlayer()` 호출을 찾습니다. 예를 들어:
+2. 다음과 같이 `useIntlayer()` 호출을 찾습니다:
 
    ```tsx
    const content = useIntlayer("app");
    ```
 
-3. 키(예: `"app"`)에서 **Command-클릭**(`⌘+Click`, macOS) 또는 **Ctrl-클릭**(Windows/Linux)합니다.
-4. VS Code가 자동으로 해당 사전 파일(예: `src/app.content.ts`)을 엽니다.
-
-### 콘텐츠 사전 관리
+3. 키(예: `"app"`)에서 **명령-클릭**(`⌘+클릭` macOS) 또는 **Ctrl+클릭**(Windows/Linux)을 합니다.
+4. VS Code가 자동으로 해당 사전 파일을 엽니다. 예: `src/app.content.ts`.
 
 ### Intlayer 탭 (활동 표시줄)
 
-사전을 탐색하고 관리하려면 사이드 탭을 사용하세요:
+사이드 탭을 사용하여 사전을 탐색하고 관리하세요:
 
 - 활동 표시줄에서 Intlayer 아이콘을 엽니다.
-- **검색(Search)**에서 실시간으로 사전과 항목을 필터링하려면 입력하세요.
-- **사전(Dictionaries)**에서는 환경, 사전, 파일을 탐색할 수 있습니다. 툴바를 사용하여 빌드(Build), 풀(Pull), 푸시(Push), 채우기(Fill), 새로고침(Refresh), 테스트(Test), 사전 파일 생성(Create Dictionary File)을 수행하세요. 사전에서 풀/푸시, 파일에서 채우기 등의 컨텍스트 작업은 마우스 오른쪽 버튼 클릭으로 실행할 수 있습니다. 현재 편집 중인 파일은 해당되는 경우 트리에서 자동으로 표시됩니다.
+- **검색**에서 입력하여 사전과 항목을 실시간으로 필터링합니다.
+- **사전**에서 환경, 사전, 파일을 탐색합니다. 툴바를 사용하여 빌드(Build), 풀(Pull), 푸시(Push), 채우기(Fill), 새로고침(Refresh), 테스트(Test), 사전 파일 생성(Create Dictionary File)을 수행할 수 있습니다. 마우스 오른쪽 버튼 클릭으로 컨텍스트 작업(사전에서 풀/푸시, 파일에서 채우기)을 사용할 수 있습니다. 현재 편집 중인 파일은 해당되는 경우 트리에서 자동으로 표시됩니다.
 
-#### 사전 빌드하기
+### 명령어 접근
 
-모든 사전 콘텐츠 파일을 생성하려면:
+명령어는 **명령 팔레트**에서 접근할 수 있습니다.
 
 ```sh
 Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
 ```
 
-**Build Dictionaries**를 검색하여 명령을 실행하세요.
-
-#### 사전 푸시하기
-
-최신 사전 콘텐츠를 업로드하려면:
-
-1. **명령 팔레트(Command Palette)**를 엽니다.
-2. **Push Dictionaries**를 검색합니다.
-3. 푸시할 사전을 선택하고 확인합니다.
-
-#### 사전 풀하기
+- **사전 빌드(Build Dictionaries)**
+- **사전 푸시(Push Dictionaries)**
+- **사전 풀(Pull Dictionaries)**
+- **사전 채우기(Fill Dictionaries)**
+- **사전 테스트(Test Dictionaries)**
+- **사전 파일 생성(Create Dictionary File)**
 
-최신 사전 콘텐츠 동기화:
+### 환경 변수 로딩
 
-1. **명령 팔레트**를 엽니다.
-2. **Pull Dictionaries**를 검색합니다.
-3. 가져올 사전을 선택합니다.
+Intlayer는 AI API 키와 Intlayer 클라이언트 ID 및 시크릿을 환경 변수에 저장할 것을 권장합니다.
 
-#### 사전 채우기
+이 확장 프로그램은 작업 공간에서 환경 변수를 로드하여 올바른 컨텍스트로 Intlayer 명령을 실행할 수 있습니다.
 
-프로젝트의 콘텐츠로 사전을 채웁니다:
+- **로드 순서(우선순위)**: `.env.<env>.local` → `.env.<env>` → `.env.local` → `.env`
+- **비파괴적**: 기존의 `process.env` 값은 덮어쓰지 않습니다.
+- **범위**: 파일은 구성된 기본 디렉터리(기본값은 작업 공간 루트)에서 해석됩니다.
 
-1. **명령 팔레트**를 엽니다.
-2. **Fill Dictionaries**를 검색합니다.
-3. 사전을 채우기 위해 명령을 실행합니다.
+#### 활성 환경 선택
 
-#### 사전 테스트
+- **명령 팔레트**: 팔레트를 열고 `Intlayer: Select Environment` 명령을 실행한 후 환경(예: `development`, `staging`, `production`)을 선택합니다. 확장 기능은 위 우선순위 목록에서 첫 번째로 사용 가능한 파일을 로드하려 시도하며, “Loaded env from .env.<env>.local”과 같은 알림을 표시합니다.
+- **설정**: `설정 → 확장 기능 → Intlayer`로 이동하여 다음을 설정합니다:
+  - **환경(Environment)**: `.env.<env>*` 파일을 해석하는 데 사용되는 환경 이름입니다.
+  - (선택 사항) **Env 파일**: 명시적인 `.env` 파일 경로입니다. 제공되면 추론된 목록보다 우선합니다.
 
-사전을 검증하고 누락된 번역을 찾습니다:
+#### 모노레포 및 사용자 지정 디렉토리
 
-1. **명령 팔레트**를 엽니다.
-2. **Test Dictionaries**를 검색합니다.
-3. 보고된 문제를 검토하고 필요에 따라 수정합니다.
+워크스페이스 루트 외부에 `.env` 파일이 있는 경우, `설정 → 확장 기능 → Intlayer`에서 **기본 디렉터리**를 설정하세요. 로더는 해당 디렉터리를 기준으로 `.env` 파일을 찾습니다.
 
 ## 문서 이력
 
-| 버전   | 날짜       | 변경 사항   |
-| ------ | ---------- | ----------- |
-| 5.5.10 | 2025-06-29 | 이력 초기화 |
+| 버전   | 날짜       | 변경 사항                                |
+| ------ | ---------- | ---------------------------------------- |
+| 6.1.5  | 2025-09-30 | 데모 GIF 추가                            |
+| 6.1.0  | 2025-09-24 | 환경 선택 섹션 추가                      |
+| 6.0.0  | 2025-09-22 | Intlayer 탭 / 채우기 및 테스트 명령 추가 |
+| 5.5.10 | 2025-06-29 | 초기 이력                                |

package/docs/pt/component_i18n.md

@@ -0,0 +1,186 @@
+---
+createdAt: 2024-03-07
+updatedAt: 2025-09-30
+title: Tornar um componente multilíngue (biblioteca i18n) em React e Next.js
+description: Aprenda como declarar e recuperar conteúdo localizado para construir um componente multilíngue em React ou Next.js com Intlayer.
+keywords:
+  - i18n
+  - componente
+  - react
+  - multilíngue
+  - next.js
+  - intlayer
+slugs:
+  - doc
+  - component
+  - i18n
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-react-template
+youtubeVideo: https://www.youtube.com/watch?v=dS9L7uJeak4
+---
+
+# Como tornar um componente multilíngue (i18n) com Intlayer
+
+Este guia mostra os passos mínimos para tornar um componente de interface multilíngue em duas configurações comuns:
+
+- React (Vite/SPA)
+- Next.js (App Router)
+
+Você primeiro declarará seu conteúdo, depois o recuperará no seu componente.
+
+## 1) Declare seu conteúdo (compartilhado para React e Next.js)
+
+Crie um arquivo de declaração de conteúdo próximo ao seu componente. Isso mantém as traduções próximas de onde são usadas e permite segurança de tipos.
+
+```ts fileName="component.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    description: t({
+      en: "A multilingual React component",
+      fr: "Un composant React multilingue",
+      es: "Un componente React multilingüe",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentContent;
+```
+
+JSON também é suportado se você preferir arquivos de configuração.
+
+```json fileName="component.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-example",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": { "en": "Hello", "fr": "Bonjour", "es": "Hola" }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "A multilingual React component",
+        "fr": "Un composant React multilingue",
+        "es": "Un componente React multilingüe"
+      }
+    }
+  }
+}
+```
+
+## 2) Recupere seu conteúdo
+
+### Caso A — Aplicação React (Vite/SPA)
+
+Abordagem padrão: use `useIntlayer` para recuperar pelo key. Isso mantém os componentes enxutos e tipados.
+
+```tsx fileName="ComponentExample.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export function ComponentExample() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Renderização do lado servidor ou fora do provider: use `react-intlayer/server` e passe um `locale` explícito quando necessário.
+
+```tsx fileName="ServerRenderedExample.tsx"
+import { useIntlayer } from "react-intlayer/server";
+
+export function ServerRenderedExample({ locale }: { locale: string }) {
+  const content = useIntlayer("component-example", locale);
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+Alternativa: `useDictionary` pode ler um objeto declarado inteiro se você preferir colocar a estrutura no local da chamada.
+
+```tsx fileName="ComponentWithDictionary.tsx"
+import { useDictionary } from "react.intlayer";
+import componentContent from "./component.content";
+
+export function ComponentWithDictionary() {
+  const { title, description } = useDictionary(componentContent);
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+### Caso B — Next.js (App Router)
+
+Prefira componentes de servidor para segurança dos dados e desempenho. Use `useIntlayer` de `next-intlayer/server` em arquivos de servidor, e `useIntlayer` de `next-intlayer` em componentes cliente.
+
+```tsx fileName="app/[locale]/example/ServerComponent.tsx"
+import { useIntlayer } from "next-intlayer/server";
+
+export default function ServerComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+```tsx fileName="app/[locale]/example/ClientComponent.tsx"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+export function ClientComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Dica: Para metadados de página e SEO, você também pode buscar conteúdo usando `getIntlayer` e gerar URLs multilíngues via `getMultilingualUrls`.
+
+## Por que a abordagem de componentes do Intlayer é a melhor
+
+- **Colocação**: Declarações de conteúdo ficam próximas aos componentes, reduzindo desvios e melhorando o reuso em sistemas de design.
+- **Segurança de tipos**: Chaves e estruturas são fortemente tipadas; traduções ausentes aparecem em tempo de build, e não em tempo de execução.
+- **Server-first**: Funciona nativamente em componentes de servidor para melhor segurança e desempenho; hooks do cliente permanecem ergonômicos.
+- **Tree-shaking**: Apenas o conteúdo usado pelo componente é incluído no pacote, mantendo os tamanhos pequenos em grandes aplicações.
+- **DX & ferramentas**: Middleware embutido, auxiliares de SEO e traduções opcionais via Editor Visual/IA agilizam o trabalho diário.
+
+Veja as comparações e padrões no resumo focado em Next.js: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+## Guias e referências relacionadas
+
+- Configuração React (Vite): https://intlayer.org/doc/environment/vite-and-react
+- React Router v7: https://intlayer.org/doc/environment/vite-and-react/react-router-v7
+- Início TanStack: https://intlayer.org/doc/environment/vite-and-react/tanstack-start
+- Configuração do Next.js: https://intlayer.org/doc/environment/nextjs
+- Por que Intlayer vs. next-intl vs. next-i18next: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+Estas páginas incluem configuração completa, provedores, roteamento e auxiliares de SEO.

package/docs/pt/vs_code_extension.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-03-17
-updatedAt: 2025-09-22
+updatedAt: 2025-09-30
 title: Extensão Oficial do VS Code
-description: Aprenda a usar a extensão Intlayer no VS Code para aprimorar seu fluxo de trabalho de desenvolvimento. Navegue rapidamente entre conteúdos localizados e gerencie seus dicionários de forma eficiente.
+description: Aprenda a usar a extensão Intlayer no VS Code para melhorar seu fluxo de trabalho de desenvolvimento. Navegue rapidamente entre conteúdos localizados e gerencie seus dicionários de forma eficiente.
 keywords:
   - Extensão VS Code
   - Intlayer
@@ -21,94 +21,38 @@ slugs:
 
 ## Visão Geral
 
-[**Intlayer**](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) é a extensão oficial do Visual Studio Code para **Intlayer**, projetada para melhorar a experiência do desenvolvedor ao trabalhar com conteúdo localizado em seus projetos.
+[**Intlayer**](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) é a extensão oficial do Visual Studio Code para o **Intlayer**, projetada para melhorar a experiência do desenvolvedor ao trabalhar com conteúdo localizado em seus projetos.
 
-![Extensão Intlayer para VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+![Extensão Intlayer para VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif?raw=true)
 
 Link da extensão: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
 
 ## Funcionalidades
 
-### Navegação Instantânea
+![Preencher dicionários](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
-**Suporte a Ir para Definição** – Use `⌘ + Clique` (Mac) ou `Ctrl + Clique` (Windows/Linux) em uma chave `useIntlayer` para abrir instantaneamente o arquivo de conteúdo correspondente.  
-**Integração Fluida** – Funciona perfeitamente com projetos **react-intlayer** e **next-intlayer**.  
-**Suporte Multilíngue** – Suporta conteúdo localizado em diferentes idiomas.  
-**Integração com VS Code** – Integra-se suavemente com a navegação e a paleta de comandos do VS Code.
+- **Navegação Instantânea** – Vá rapidamente para o arquivo de conteúdo correto ao clicar em uma chave `useIntlayer`.
+- **Preencher Dicionários** – Preencha dicionários com conteúdo do seu projeto.
 
-### Comandos de Gerenciamento de Dicionários
+![Listar comandos](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_list_commands.gif?raw=true)
 
-Gerencie seus dicionários de conteúdo diretamente do VS Code:
+- **Acesso fácil aos comandos do Intlayer** – Construir, enviar, puxar, preencher e testar dicionários de conteúdo com facilidade.
 
-- **Construir Dicionários** – Gere arquivos de conteúdo com base na estrutura do seu projeto.
-- **Enviar Dicionários** – Faça upload do conteúdo mais recente do dicionário para o seu repositório.
-- **Puxar Dicionários** – Sincronize o conteúdo mais recente do dicionário do seu repositório para o seu ambiente local.
-- **Preencher Dicionários** – Popule os dicionários com conteúdo do seu projeto.
-- **Testar Dicionários** – Identifique traduções faltantes ou incompletas.
+![Criar arquivo de conteúdo](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_create_content_file.gif?raw=true)
 
-### Gerador de Declaração de Conteúdo
+- **Gerador de Declaração de Conteúdo** – Criar arquivos de conteúdo de dicionário em vários formatos (`.ts`, `.esm`, `.cjs`, `.json`).
 
-Gere facilmente arquivos de dicionário estruturados em diferentes formatos:
+![Testar dicionários](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_test_missing_dictionary.gif?raw=true)
 
-Se você estiver trabalhando em um componente, ele gerará o arquivo `.content.{ts,tsx,js,jsx,mjs,cjs,json}` para você.
+- **Testar Dicionários** – Testar dicionários para traduções ausentes.
 
-Exemplo de componente:
+![Reconstruir dicionário](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_rebuild_dictionary.gif?raw=true)
 
-```tsx fileName="src/components/MyComponent/index.tsx"
-const MyComponent = () => {
-  const { myTranslatedContent } = useIntlayer("my-component");
+- **Mantenha seus dicionários atualizados** – Mantenha seus dicionários atualizados com o conteúdo mais recente do seu projeto.
 
-  return <span>{myTranslatedContent}</span>;
-};
-```
-
-Arquivo gerado no formato TypeScript:
-
-```tsx fileName="src/components/MyComponent/index.content.ts"
-import { t, type Dictionary } from "intlayer";
-
-const componentContent = {
-  key: "my-component",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
-
-export default componentContent;
-```
-
-Formatos disponíveis:
-
-- **TypeScript (`.ts`)**
-- **ES Module (`.esm`)**
-- **CommonJS (`.cjs`)**
-- **JSON (`.json`)**
-
-### Aba Intlayer (Barra de Atividades)
+![Aba Intlayer (Barra de Atividades)](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_search_dictionary.gif?raw=true)
 
-Abra a aba Intlayer clicando no ícone do Intlayer na Barra de Atividades do VS Code. Ela contém duas visualizações:
-
-- **Pesquisar**: Uma barra de pesquisa ao vivo para filtrar rapidamente os dicionários e seu conteúdo. Digitar atualiza os resultados instantaneamente.
-- **Dicionários**: Uma visualização em árvore dos seus ambientes/projetos, chaves dos dicionários e os arquivos que contribuem com entradas. Você pode:
-  - Clicar em um arquivo para abri-lo no editor.
-  - Usar a barra de ferramentas para executar ações: Build, Pull, Push, Fill, Refresh, Test e Create Dictionary File.
-  - Usar o menu de contexto para ações específicas do item:
-    - Em um dicionário: Pull ou Push
-    - Em um arquivo: Fill Dictionary
-  - Quando você alternar de editor, a árvore revelará o arquivo correspondente se ele pertencer a um dicionário.
-
-## Instalação
-
-Você pode instalar o **Intlayer** diretamente no Marketplace do VS Code:
-
-1. Abra o **VS Code**.
-2. Vá para o **Marketplace de Extensões**.
-3. Pesquise por **"Intlayer"**.
-4. Clique em **Instalar**.
+- **Aba Intlayer (Barra de Atividades)** – Navegue e pesquise dicionários em uma aba lateral dedicada com barra de ferramentas e ações de contexto (Construir, Puxar, Enviar, Preencher, Atualizar, Testar, Criar Arquivo).
 
 ## Uso
 
@@ -121,63 +65,58 @@ Você pode instalar o **Intlayer** diretamente no Marketplace do VS Code:
    const content = useIntlayer("app");
    ```
 
-3. **Command-click** (`⌘+Click` no macOS) ou **Ctrl+Click** (no Windows/Linux) na chave (ex.: `"app"`).
+3. **Clique com comando** (`⌘+Clique` no macOS) ou **Ctrl+Clique** (no Windows/Linux) na chave (por exemplo, `"app"`).
 4. O VS Code abrirá automaticamente o arquivo de dicionário correspondente, por exemplo, `src/app.content.ts`.
 
-### Gerenciando Dicionários de Conteúdo
-
 ### Aba Intlayer (Barra de Atividades)
 
-Use a aba lateral para navegar e gerenciar os dicionários:
+Use a aba lateral para navegar e gerenciar dicionários:
 
 - Abra o ícone do Intlayer na Barra de Atividades.
 - Em **Pesquisar**, digite para filtrar dicionários e entradas em tempo real.
 - Em **Dicionários**, navegue por ambientes, dicionários e arquivos. Use a barra de ferramentas para Construir, Puxar, Enviar, Preencher, Atualizar, Testar e Criar Arquivo de Dicionário. Clique com o botão direito para ações de contexto (Puxar/Enviar em dicionários, Preencher em arquivos). O arquivo atual do editor é revelado automaticamente na árvore quando aplicável.
 
-#### Construindo Dicionários
+### Acessando os comandos
 
-Gere todos os arquivos de conteúdo dos dicionários com:
+Você pode acessar os comandos a partir da **Paleta de Comandos**.
 
 ```sh
 Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
 ```
 
-Pesquise por **Construir Dicionários** e execute o comando.
-
-#### Enviando Dicionários
-
-Envie o conteúdo mais recente dos dicionários:
-
-1. Abra a **Paleta de Comandos**.
-2. Pesquise por **Enviar Dicionários**.
-3. Selecione os dicionários para enviar e confirme.
-
-#### Puxando Dicionários
+- **Construir Dicionários**
+- **Enviar Dicionários**
+- **Puxar Dicionários**
+- **Preencher Dicionários**
+- **Testar Dicionários**
+- **Criar Arquivo de Dicionário**
 
-Sincronize o conteúdo mais recente do dicionário:
+### Carregando Variáveis de Ambiente
 
-1. Abra a **Paleta de Comandos**.
-2. Procure por **Puxar Dicionários**.
-3. Escolha os dicionários para puxar.
+O Intlayer recomenda armazenar suas chaves de API de IA, assim como o ID e o segredo do cliente Intlayer, em variáveis de ambiente.
 
-#### Preenchendo Dicionários
+A extensão pode carregar variáveis de ambiente do seu espaço de trabalho para executar comandos do Intlayer com o contexto correto.
 
-Preencha os dicionários com conteúdo do seu projeto:
+- **Ordem de carregamento (por prioridade)**: `.env.<env>.local` → `.env.<env>` → `.env.local` → `.env`
+- **Não destrutivo**: valores existentes em `process.env` não são sobrescritos.
+- **Escopo**: os arquivos são resolvidos a partir do diretório base configurado (padrão é a raiz do espaço de trabalho).
 
-1. Abra a **Paleta de Comandos**.
-2. Procure por **Preencher Dicionários**.
-3. Execute o comando para popular os dicionários.
+#### Selecionando o ambiente ativo
 
-#### Testando Dicionários
+- **Paleta de Comandos**: abra a paleta e execute `Intlayer: Select Environment`, depois escolha o ambiente (por exemplo, `development`, `staging`, `production`). A extensão tentará carregar o primeiro arquivo disponível na lista de prioridade acima e mostrará uma notificação como “Loaded env from .env.<env>.local”.
+- **Configurações**: vá para `Settings → Extensions → Intlayer` e defina:
+  - **Environment**: o nome do ambiente usado para resolver arquivos `.env.<env>*`.
+  - (Opcional) **Env File**: um caminho explícito para um arquivo `.env`. Quando fornecido, ele tem precedência sobre a lista inferida.
 
-Valide os dicionários e encontre traduções faltantes:
+#### Monorepos e diretórios personalizados
 
-1. Abra a **Paleta de Comandos**.
-2. Procure por **Testar Dicionários**.
-3. Revise os problemas relatados e corrija conforme necessário.
+Se os seus arquivos `.env` estiverem fora da raiz do espaço de trabalho, defina o **Diretório Base** em `Configurações → Extensões → Intlayer`. O carregador irá procurar arquivos `.env` relativos a esse diretório.
 
 ## Histórico do Documento
 
-| Versão | Data       | Alterações        |
-| ------ | ---------- | ----------------- |
-| 5.5.10 | 2025-06-29 | Histórico inicial |
+| Versão | Data       | Alterações                                 |
+| ------ | ---------- | ------------------------------------------ |
+| 6.1.5  | 2025-09-30 | Adicionado gif de demonstração             |
+| 6.1.0  | 2025-09-24 | Adicionada seção de seleção de ambiente    |
+| 6.0.0  | 2025-09-22 | Aba Intlayer / Comandos Preencher & Testar |
+| 5.5.10 | 2025-06-29 | Histórico inicial                          |