generaltranslation · JoshKappler · Jul 18, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md
@@ -407,7 +407,7 @@ A few optional fields appear on specific page types:
 ## Page structure
 
 1. **Frontmatter title:** the docs layout renders the `title` as the page H1. Do not add a `#` heading to the body.
-2. **Intro:** 1–3 short sentences with no heading, stating what the page is and when to use it. Optionally one more italicized short line for constraints or scope.
+2. **Intro:** 1–3 short sentences with no heading that add substance beyond the `description`: behavior, inputs, or when to use it. The docs layout already renders the `description` beneath the title, so the intro must not restate or paraphrase it. On reference pages especially, do not open with the description's summary sentence. Optionally one more italicized short line for constraints or scope.
 3. **Sections:** use `##` for top-level body sections.
 
 
@@ -695,6 +695,7 @@ These patterns are **blocked by CI** and will fail the build, so never use them
 ## Consistency checks before finishing
 
 - The page reflects real system behavior (verified against code and existing docs), not just restated formatting.
+- The intro does not restate the frontmatter `description` (the layout renders the description under the title); the body opens with new detail.
 - Depth and vocabulary match the page audience.
 - Sections are grouped into a few meaningful H2s with H3 subsections, not many small one-off H2s. Consolidate or restructure if there are more than 6 H2 subsections.
 - First mention of the product on the page (and in the description) uses **General Translation**, not GT.

diff --git a/docs/en-US/cli/guides/branching.mdx b/docs/en-US/cli/guides/branching.mdx
@@ -11,7 +11,7 @@ related:
 
 ---
 
-Branching tracks translations separately for each git branch. Use it when a feature branch adds or changes content and you want those translations isolated from production until the branch merges.
+Use branching when a feature branch adds or changes content and you want those translations isolated from production until the branch merges.
 
 *Note: Branching is a General Translation Cloud feature and requires a paid plan. Without one, creating a non-default branch falls back to the default branch.*
 

diff --git a/docs/en-US/cli/reference/commands/init.mdx b/docs/en-US/cli/reference/commands/init.mdx
@@ -5,9 +5,9 @@ description: Run the General Translation setup wizard to configure a project. AP
 
 ---
 
-Runs the setup wizard that prepares a project for General Translation. This is the default command — running `npx gt` with no command runs `init`.
+`init` is the default command: running `npx gt` with no command runs it.
 
-The wizard detects your framework and, depending on the project, installs dependencies, configures your framework, creates a `gt.config.json`, and generates credentials. For a step-by-step walkthrough, see [Configuring the CLI](/docs/cli/guides/configuring).
+The setup wizard detects your framework and, depending on the project, installs dependencies, configures your framework, creates a `gt.config.json`, and generates credentials. For a step-by-step walkthrough, see [Configuring the CLI](/docs/cli/guides/configuring).
 
 ```bash
 npx gt init

diff --git a/docs/en-US/cli/reference/formats/plain-text-files.mdx b/docs/en-US/cli/reference/formats/plain-text-files.mdx
@@ -5,7 +5,7 @@ description: Translate plain text files with the General Translation CLI. API re
 
 ---
 
-The CLI translates arbitrary plain text (`txt`) files.
+The entire `txt` file is treated as translatable content, so no markup or structure is preserved or skipped.
 
 ## Configuration [#config]
 

diff --git a/docs/en-US/cli/reference/keyed-metadata.mdx b/docs/en-US/cli/reference/keyed-metadata.mdx
@@ -5,7 +5,7 @@ description: Attach per-key translation instructions to General Translation JSON
 
 ---
 
-Keyed metadata attaches translation instructions to individual keys in your JSON and YAML files. You provide a companion metadata file that mirrors the source file's key structure, with a metadata object at each leaf.
+You provide a companion metadata file that mirrors the source file's key structure, with a metadata object at each leaf. Each object holds instructions for translating that one key.
 
 The CLI detects companion metadata files automatically, validates them against the source structure, and sends them to the translation engine.
 

diff --git a/docs/en-US/integrations/mintlify/guides/managing-translations.mdx b/docs/en-US/integrations/mintlify/guides/managing-translations.mdx
@@ -10,7 +10,7 @@ related:
 
 ---
 
-After your Mintlify docs are set up, use this guide to add or remove languages, keep translations current as your content changes, and edit generated translations.
+After your Mintlify docs are set up and translating, use this guide to keep them current as your content and language needs change.
 
 ## Keep translations up to date [#continuous]
 

diff --git a/docs/en-US/integrations/sanity/reference/plugin-configuration.mdx b/docs/en-US/integrations/sanity/reference/plugin-configuration.mdx
@@ -5,7 +5,7 @@ description: Configure the General Translation gt-sanity plugin for Sanity Studi
 
 ---
 
-Configure General Translation in Sanity Studio with the `gtPlugin` function. Pass a single options object.
+Register General Translation in your Sanity config with the `gtPlugin` function. Pass it a single options object.
 
 ```ts title="sanity.config.ts"
 import { gtPlugin } from 'gt-sanity';

diff --git a/docs/en-US/integrations/storyblok/reference/connection.mdx b/docs/en-US/integrations/storyblok/reference/connection.mdx
@@ -5,7 +5,7 @@ description: Reference for the settings used to connect a Storyblok space to Gen
 
 ---
 
-The settings used to connect a Storyblok space to General Translation. You provide them once in the **Connect** dialog at **Project > Integrations**; General Translation stores them on the Project and uses them to call the Storyblok Management API.
+You provide the connection settings once in the **Connect** dialog at **Project > Integrations**; General Translation stores them on the Project and uses them to call the Storyblok Management API.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/integrations/storyblok/reference/supported-content.mdx b/docs/en-US/integrations/storyblok/reference/supported-content.mdx
@@ -5,7 +5,7 @@ description: Reference for the Storyblok field types General Translation transla
 
 ---
 
-Which Storyblok field types General Translation translates, how it handles rich text and tables, and the data format it uses. General Translation walks each story's content tree, recurses into nested blocks, and extracts translatable fields.
+General Translation walks each story's content tree, recurses into nested blocks, and extracts translatable fields.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/node/reference/functions/declare-var.mdx b/docs/en-US/node/reference/functions/declare-var.mdx
@@ -5,7 +5,7 @@ description: Mark a value as non-derivable within a General Translation derive c
 
 ---
 
-Marks a value as non-derivable — content that cannot be statically analyzed by the General Translation compiler. Use `declareVar` inside a [`derive`](/docs/node/reference/functions/derive) call to isolate the part of an expression that must be treated as a runtime variable.
+A non-derivable value is one the General Translation compiler cannot statically analyze. Use `declareVar` inside a [`derive`](/docs/node/reference/functions/derive) call to isolate the part of an expression that must be treated as a runtime variable.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/node/reference/functions/derive.mdx b/docs/en-US/node/reference/functions/derive.mdx
@@ -5,7 +5,7 @@ description: Mark computed content as derivable for General Translation extracti
 
 ---
 
-Marks content that is computed from source code as derivable by the General Translation compiler and CLI. Use `derive` when a translated string interpolates a value that should be discovered during extraction rather than treated as a runtime variable.
+Derivable content is computed in source code but resolves to a fixed set of values the CLI can translate. Use `derive` when a translated string interpolates a value that should be discovered during extraction rather than treated as a runtime variable.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/node/reference/functions/get-locale.mdx b/docs/en-US/node/reference/functions/get-locale.mdx
@@ -5,7 +5,7 @@ description: Read the active locale for the current request in General Translati
 
 ---
 
-Returns the current locale for the active request context. Call it inside a [`withGT`](/docs/node/reference/functions/with-gt) scope to read the locale bound for the request.
+Returns the active locale as a BCP 47 code. Call it inside a [`withGT`](/docs/node/reference/functions/with-gt) scope to read the locale bound for the request.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/node/reference/functions/get-locales.mdx b/docs/en-US/node/reference/functions/get-locales.mdx
@@ -5,7 +5,7 @@ description: List the supported locales configured in General Translation gt-nod
 
 ---
 
-Returns the list of supported locales configured in [`initializeGT`](/docs/node/reference/functions/initialize-gt).
+Returns the array of supported BCP 47 locale codes you set in [`initializeGT`](/docs/node/reference/functions/initialize-gt).
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-currency.mdx b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-currency.mdx
@@ -5,7 +5,7 @@ description: Format a currency value by locale on a GT instance. API reference f
 
 ---
 
-Formats a numeric value as a localized currency string on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation uses the built-in `Intl.NumberFormat` API with the currency style, so amounts render with the correct symbol, grouping, and decimal conventions for each locale.
+General Translation uses the built-in `Intl.NumberFormat` API with the currency style, so amounts render with the correct symbol, grouping, and decimal conventions for each locale.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-list.mdx b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-list.mdx
@@ -5,7 +5,7 @@ description: Format an array into a locale-aware list string on a GT instance. A
 
 ---
 
-Formats an array into a single locale-aware list string on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation uses the built-in `Intl.ListFormat` API to join items with the correct separators and conjunction ("and") or disjunction ("or") wording for each locale.
+General Translation uses the built-in `Intl.ListFormat` API to join items with the correct separators and conjunction ("and") or disjunction ("or") wording for each locale.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/gt-class-methods/locales/determine-locale.mdx b/docs/en-US/platform/core/reference/gt-class-methods/locales/determine-locale.mdx
@@ -5,7 +5,7 @@ description: Find the best matching locale from a list of approved locales. API
 
 ---
 
-Determines the best matching locale from a list of approved locales based on user preferences, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation implements locale negotiation to find the most suitable locale when an exact match is not available.
+General Translation implements locale negotiation to find the most suitable locale when an exact match is not available.
 
 ## Overview [#overview]
 

diff --git a/...en-US/platform/core/reference/gt-class-methods/locales/get-locale-direction.mdx b/...en-US/platform/core/reference/gt-class-methods/locales/get-locale-direction.mdx
@@ -5,7 +5,7 @@ description: Return the text direction for a locale. API reference for getLocale
 
 ---
 
-Determines the text direction of a locale on a [GT](/docs/platform/core/reference/gt-class/constructor) instance, using the `Intl.Locale` API. General Translation returns `'ltr'` for left-to-right languages or `'rtl'` for right-to-left languages.
+General Translation returns `'ltr'` for left-to-right languages or `'rtl'` for right-to-left languages.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/gt-class-methods/locales/is-same-dialect.mdx b/docs/en-US/platform/core/reference/gt-class-methods/locales/is-same-dialect.mdx
@@ -5,7 +5,7 @@ description: Check whether two locales represent the same dialect. API reference
 
 ---
 
-Checks whether multiple BCP-47 locale codes represent the same dialect on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation compares the language and region components of locale codes to determine whether they represent the same linguistic variety.
+General Translation compares the language and region components of locale codes to determine whether they represent the same linguistic variety.
 
 ## Overview [#overview]
 

diff --git a/...en-US/platform/core/reference/gt-class-methods/locales/resolve-alias-locale.mdx b/...en-US/platform/core/reference/gt-class-methods/locales/resolve-alias-locale.mdx
@@ -5,7 +5,7 @@ description: Resolve a locale alias to the locale code used by a custom mapping.
 
 ---
 
-Resolves a canonical locale code back to its original alias locale code when a custom mapping is configured, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. This is the inverse of [`resolveCanonicalLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale). General Translation uses aliases so you can expose your own locale codes while mapping them to standard BCP-47 codes internally.
+Returns the alias code you exposed for a canonical locale, when a custom mapping is configured, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. This is the inverse of [`resolveCanonicalLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale). General Translation uses aliases so you can expose your own locale codes while mapping them to standard BCP-47 codes internally.
 
 ## Overview [#overview]
 

diff --git a/...S/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale.mdx b/...S/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale.mdx
@@ -5,7 +5,7 @@ description: Resolve a locale alias to its canonical locale code on a GT instanc
 
 ---
 
-Resolves a locale alias to the canonical BCP-47 locale code used internally, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. This is the inverse of [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale). General Translation uses a custom mapping so you can expose your own locale codes while translating and formatting against standard codes internally.
+Returns the canonical BCP-47 code that General Translation uses internally for a locale alias, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. This is the inverse of [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale). General Translation uses a custom mapping so you can expose your own locale codes while translating and formatting against standard codes internally.
 
 ## Overview [#overview]
 

diff --git a/...en-US/platform/core/reference/gt-class-methods/translation/check-job-status.mdx b/...en-US/platform/core/reference/gt-class-methods/translation/check-job-status.mdx
@@ -5,7 +5,7 @@ description: Check the current status of a translation or setup job. API referen
 
 ---
 
-Checks the current status of one or more General Translation jobs by their identifiers. Use it to monitor the asynchronous operations started by [`setupProject`](/docs/platform/core/reference/gt-class-methods/translation/setup-project) or [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files).
+Monitor the asynchronous operations started by [`setupProject`](/docs/platform/core/reference/gt-class-methods/translation/setup-project) or [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) by polling their job status.
 
 ## Overview [#overview]
 

diff --git a/...US/platform/core/reference/gt-class-methods/translation/download-file-batch.mdx b/...US/platform/core/reference/gt-class-methods/translation/download-file-batch.mdx
@@ -5,7 +5,7 @@ description: Download multiple translated files in one request. API reference fo
 
 ---
 
-Downloads multiple source or translation files in a single batch request with General Translation. Use it instead of many individual [`downloadFile`](/docs/platform/core/reference/gt-class-methods/translation/download-file) calls to reduce network overhead.
+Fetch several source or translation files in one request instead of making many individual [`downloadFile`](/docs/platform/core/reference/gt-class-methods/translation/download-file) calls, which reduces network overhead.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/gt-class-methods/translation/translate.mdx b/docs/en-US/platform/core/reference/gt-class-methods/translation/translate.mdx
@@ -5,7 +5,7 @@ description: Translate one string or structured content entry into a target loca
 
 ---
 
-Translates a single string or structured content entry from a source locale into a target locale. This is the primary translation method on a [GT](/docs/platform/core/reference/gt-class/constructor) instance.
+`translate` is the primary translation method on a [GT](/docs/platform/core/reference/gt-class/constructor) instance, for translating one string or structured content entry at a time.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/gt-class/set-config.mdx b/docs/en-US/platform/core/reference/gt-class/set-config.mdx
@@ -5,7 +5,7 @@ description: Update configuration on an existing GT instance. API reference for
 
 ---
 
-Updates the configuration of an existing [GT](/docs/platform/core/reference/gt-class/constructor) instance. Use it to change API credentials, locales, and other settings after the instance was created with General Translation.
+Change the API credentials, locales, and other settings of a [GT](/docs/platform/core/reference/gt-class/constructor) instance after it was created, without constructing a new one.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/types/gt-constructor-params.mdx b/docs/en-US/platform/core/reference/types/gt-constructor-params.mdx
@@ -5,7 +5,7 @@ description: Configuration options accepted by the GT constructor. API reference
 
 ---
 
-`GTConstructorParams` defines the configuration options accepted by the General Translation [Constructor](/docs/platform/core/reference/gt-class/constructor) when initializing a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance.
+`GTConstructorParams` is the object passed to the General Translation [constructor](/docs/platform/core/reference/gt-class/constructor) to configure a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance's API credentials, locales, and endpoints.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/types/jsx-element.mdx b/docs/en-US/platform/core/reference/types/jsx-element.mdx
@@ -5,7 +5,7 @@ description: Structured JSX-like element used in translatable content. API refer
 
 ---
 
-`JsxElement` represents a structured, HTML-like element inside translatable [`JsxChildren`](/docs/platform/core/reference/types/jsx-children) content. It captures an element's tag, identifier, GT properties, and child content in a compact, serializable form.
+`JsxElement` lets General Translation preserve an element's structure inside translatable [`JsxChildren`](/docs/platform/core/reference/types/jsx-children) content. It captures an element's tag, identifier, GT properties, and child content in a compact, serializable form.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/core/reference/types/variable.mdx b/docs/en-US/platform/core/reference/types/variable.mdx
@@ -5,7 +5,7 @@ description: Placeholder for dynamic content in translatable messages. API refer
 
 ---
 
-`Variable` represents a placeholder for dynamic content inside translatable [`JsxChildren`](/docs/platform/core/reference/types/jsx-children) content. Each variable has a key and an optional formatting type so General Translation can substitute and format runtime values.
+`Variable` carries a key and an optional formatting type, so General Translation can substitute and format runtime values inside translatable [`JsxChildren`](/docs/platform/core/reference/types/jsx-children) content.
 
 ## Overview [#overview]
 

diff --git a/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx b/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx
@@ -10,8 +10,6 @@ related:
 
 ---
 
-Use the Dashboard to review translations and make manual edits. 
-
 ## Basic review workflow [#basic-review-workflow]
 
 1. Open your Project in the Dashboard.

diff --git a/docs/en-US/platform/dashboard/reference/project-settings.mdx b/docs/en-US/platform/dashboard/reference/project-settings.mdx
@@ -3,7 +3,7 @@ title: "Project settings"
 description: "Project settings control how an individual Project appears and how its translations are delivered."
 ---
 
-Project settings control how an individual Project appears and how its translations are delivered.
+Each Project in the Dashboard has its own settings, separate from Organization-wide settings. Use them to rename the Project, change its source locale, enable CDN delivery or AI Context, copy the Project ID, and delete the Project.
 
 ## General settings [#general-settings]
 

diff --git a/docs/en-US/platform/dashboard/reference/supported-locales.mdx b/docs/en-US/platform/dashboard/reference/supported-locales.mdx
@@ -5,7 +5,7 @@ description: Search the locales supported by the General Translation platform.
 
 ---
 
-A list of the 110+ locales currently supported by General Translation. A machine-readable list is available at [`/locales.json`](/locales.json).
+For programmatic use, the full list of 110+ supported locales is served at [`/locales.json`](/locales.json).
 
 ## Search locales [#search-locales]
 

diff --git a/docs/en-US/platform/index.mdx b/docs/en-US/platform/index.mdx
@@ -5,7 +5,7 @@ description: Browse docs for the General Translation Platform, including the Das
 
 ---
 
-Browse docs for the General Translation Platform.
+These sections cover the Dashboard, the core `generaltranslation` library, Locadex, and the HTTP API.
 
 <Cards>
   <Card title="Dashboard" href="/docs/platform/dashboard/get-started">

diff --git a/docs/en-US/platform/locadex/reference/agent.mdx b/docs/en-US/platform/locadex/reference/agent.mdx
@@ -5,9 +5,7 @@ description: Reference for the Locadex Agent page, repository status, languages,
 
 ---
 
-The Agent page is the main status page for Locadex.
-
-Open it from **Locadex > Agent** in the Project sidebar.
+Open the Agent page from **Locadex > Agent** in the Project sidebar.
 
 ## Repository [#repository]
 

diff --git a/docs/en-US/platform/locadex/reference/vm-image.mdx b/docs/en-US/platform/locadex/reference/vm-image.mdx
@@ -5,9 +5,7 @@ description: Reference for the sandbox environment Locadex uses to run workflows
 
 ---
 
-Locadex runs workflows in a sandboxed environment.
-
-The sandbox installs dependencies, runs configured commands, updates files, and prepares pull request changes.
+The sandbox environment where Locadex runs each workflow installs dependencies, runs configured commands, updates files, and prepares pull request changes.
 
 ## Environment variables [#environment-variables]
 

diff --git a/docs/en-US/platform/openapi/reference/context/context-status.mdx b/docs/en-US/platform/openapi/reference/context/context-status.mdx
@@ -6,7 +6,7 @@ description: Track the status of a General Translation context generation job. A
 method: GET
 ---
 
-Returns the status of a context generation job started by [Generate translation context](/docs/platform/openapi/reference/context/generate-context).
+Look up a context generation job created by [Generate translation context](/docs/platform/openapi/reference/context/generate-context) to check its progress.
 
 *Note: this endpoint is retained for backward compatibility. For new integrations, use [Get translation job status](/docs/platform/openapi/reference/translation/job-status), which reports status for any queued job.*
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,7 +11,7 @@ related: @@
     ---
-    Branching tracks translations separately for each git branch. Use it when a feature branch adds or changes content and you want those translations isolated from production until the branch merges.
+    Use branching when a feature branch adds or changes content and you want those translations isolated from production until the branch merges.
     *Note: Branching is a General Translation Cloud feature and requires a paid plan. Without one, creating a non-default branch falls back to the default branch.*
@@ Expand Down @@