From 49bf519b07f6c78f27c76d64d7b4e4ac2fb553fc Mon Sep 17 00:00:00 2001 From: Jackie Chen <49351102+pie575@users.noreply.github.com> Date: Sat, 1 Aug 2026 09:51:58 -0700 Subject: [PATCH 01/13] fix: describe Ask AI billing in LCUs (#435) --- docs/en-US/platform/dashboard/guides/managing-billing.mdx | 4 ++-- docs/en-US/platform/dashboard/guides/using-ask-ai.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en-US/platform/dashboard/guides/managing-billing.mdx b/docs/en-US/platform/dashboard/guides/managing-billing.mdx index ff1fffe59..4c85520e3 100644 --- a/docs/en-US/platform/dashboard/guides/managing-billing.mdx +++ b/docs/en-US/platform/dashboard/guides/managing-billing.mdx @@ -33,7 +33,7 @@ Review consumption under **Organization > Usage > Translations**. Filter by Proj ### How usage is metered [#usage-metering] - **Translation workflows** are metered by input tokens, workflow type, and file format. -- **Ask AI** uses Organization credits at 10% of the underlying model token cost. +- **Ask AI** is charged in **Locadex Compute Units (LCUs)**. - **Google Slides** adds a per-slide **Layout Processing** charge to its translation workflow. This charge has no context surcharge. - **Context** adds a surcharge based on the input tokens and the amount of Project context provided. - **Locadex** agent runs are metered in **Locadex Compute Units (LCUs)**. An LCU measures the resources an agent uses to run end to end. @@ -92,4 +92,4 @@ Upgrading removes your rate limit and also unlocks features including: Locadex, Enterprise plans include custom pricing and terms for larger teams, including: custom integrations, a custom SLA, forward-deployed engineers, and enterprise security and support. -Join teams like Ramp, Cursor, and Profound. [Contact](https://generaltranslation.com/en-US/enterprise) the General Translation team to set up an Enterprise plan. \ No newline at end of file +Join teams like Ramp, Cursor, and Profound. [Contact](https://generaltranslation.com/en-US/enterprise) the General Translation team to set up an Enterprise plan. diff --git a/docs/en-US/platform/dashboard/guides/using-ask-ai.mdx b/docs/en-US/platform/dashboard/guides/using-ask-ai.mdx index 0811368e5..eb17b7048 100644 --- a/docs/en-US/platform/dashboard/guides/using-ask-ai.mdx +++ b/docs/en-US/platform/dashboard/guides/using-ask-ai.mdx @@ -35,7 +35,7 @@ Chats are scoped to your user and current workspace. Switching Organizations sta ## Usage and billing [#usage-billing] -Ask AI is available on every plan and uses Organization credits. Each response is charged at 10% of the underlying model token cost. An Organization without a billing account uses the same free monthly allowance as free translations. +Ask AI is available on every plan and is charged in Locadex Compute Units (LCUs). Your workspace credit balance is the usage ceiling; Ask AI has no separate daily message or spending limit. Short per-minute limits prevent bursts. If a request is blocked, the panel explains whether to wait briefly, add credits, or review billing. From 8830baf5e02a73b098e7e130990ae7f7c511fbdb Mon Sep 17 00:00:00 2001 From: "cursor[bot]" <206951365+cursor[bot]@users.noreply.github.com> Date: Sat, 1 Aug 2026 13:26:13 -0700 Subject: [PATCH 02/13] fix: sync docs with recent product behavior (#434) Co-authored-by: Cursor Agent --- devlog/en-US/local-edits.mdx | 6 ++++-- docs/en-US/cli/guides/managing-translations.mdx | 4 ++-- docs/en-US/cli/reference/commands/download.mdx | 2 +- docs/en-US/cli/reference/config.mdx | 2 +- docs/en-US/cli/reference/formats/lottie-files.mdx | 10 ++++++++++ .../platform/dashboard/guides/managing-billing.mdx | 6 +++--- 6 files changed, 21 insertions(+), 9 deletions(-) diff --git a/devlog/en-US/local-edits.mdx b/devlog/en-US/local-edits.mdx index 9b74fc255..3a20138dd 100644 --- a/devlog/en-US/local-edits.mdx +++ b/devlog/en-US/local-edits.mdx @@ -7,9 +7,11 @@ tags: ['gtx-cli', 'save-local', 'translate'] ## Overview -In **gtx-cli 2.4.0**, we've added a new way to save your local translation edits directly from the CLI. +In **gtx-cli 2.4.0**, we've added a new way to save your local translation edits directly from the CLI. This means you can now make translation changes locally, persist them, and keep everything in sync with your project without touching the dashboard. +_Version note: This post describes the 2.4.0 behavior. In `gt` and `gtx-cli` 2.16.0, pass `--save-local` to [`translate`](/docs/cli/reference/commands/translate) to run the save step._ + --- ## The `save-local` Command @@ -57,7 +59,7 @@ Files to translate: ## What Happens When Sources Change -You might wonder: _what if I edit the source file after making local translation edits?_ +You might wonder: _what if I edit the source file after making local translation edits?_ In earlier versions, that would have triggered a full retranslation that wiped your custom changes. In 2.4.0, the CLI is smarter. Even when a source update causes a retranslation, your previous local edits persist. They're incorporated into the new translation automatically. diff --git a/docs/en-US/cli/guides/managing-translations.mdx b/docs/en-US/cli/guides/managing-translations.mdx index 855f95f69..8a62fd4a1 100644 --- a/docs/en-US/cli/guides/managing-translations.mdx +++ b/docs/en-US/cli/guides/managing-translations.mdx @@ -49,13 +49,13 @@ If some locales are still processing, the download skips them. Re-run [`gt downl ## Stage translations for review [#review] -If your Project uses human review, use [`gt stage`](/docs/cli/reference/commands/stage) instead of translating directly. It works like [`translate`](/docs/cli/reference/commands/translate) but holds the results for approval rather than downloading or publishing them. +If your Project uses human review, use [`gt stage`](/docs/cli/reference/commands/stage) to submit translation work without downloading or publishing the results in the same run. Review-gated Projects hold completed translations for approval. ```bash npx gt stage ``` -Running [`stage`](/docs/cli/reference/commands/stage) sets `stageTranslations: true` in your `gt.config.json`. After translations are approved, run [`gt translate`](/docs/cli/reference/commands/translate) to download them. While `stageTranslations` is enabled, [`translate`](/docs/cli/reference/commands/translate) only downloads the versions you have staged; if nothing has been staged, there is nothing to download. +Running [`stage`](/docs/cli/reference/commands/stage) sets `stageTranslations: true` in your `gt.config.json`. After translations are approved, run [`gt download`](/docs/cli/reference/commands/download). [`gt translate`](/docs/cli/reference/commands/translate) can also download a previously staged version. While `stageTranslations` is enabled, [`translate`](/docs/cli/reference/commands/translate) only downloads versions you have staged; if nothing has been staged, it exits with an error. ## Save local edits [#save-local] diff --git a/docs/en-US/cli/reference/commands/download.mdx b/docs/en-US/cli/reference/commands/download.mdx index 461ed3da7..f89748358 100644 --- a/docs/en-US/cli/reference/commands/download.mdx +++ b/docs/en-US/cli/reference/commands/download.mdx @@ -38,7 +38,7 @@ Files that are still processing are skipped. Re-run `gt download` to fetch them | `--dry-run` | Parse and validate without calling the API. | `boolean` | Yes | `false` | | `--force` | Invalidate cached translations and re-translate. | `boolean` | Yes | `false` | | `--force-download` | Overwrite local files, bypassing `gt-lock.json` checks. | `boolean` | Yes | `false` | -| `--save-local` | Detect and save local edits before downloading. | `boolean` | Yes | `false` | +| `--save-local` | Accepted by the shared flag parser, but does not save edits during a download-only run. | `boolean` | Yes | `false` | | `--publish` | Publish translations to the CDN. | `boolean` | Yes | `false` | | `--enable-branching` | Enable branch-based tracking. | `boolean` | Yes | — | | `--branch ` | Branch name instead of auto-detecting. | `string` | Yes | — | diff --git a/docs/en-US/cli/reference/config.mdx b/docs/en-US/cli/reference/config.mdx index 3419d636a..6b03f23d3 100644 --- a/docs/en-US/cli/reference/config.mdx +++ b/docs/en-US/cli/reference/config.mdx @@ -128,7 +128,7 @@ The CLI syncs matching fonts before [`gt stage`](/docs/cli/reference/commands/st **Type** `boolean` · **Optional** · **Default** `false` -When `true`, translated files are published to the General Translation CDN after [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload), or [`save-local`](/docs/cli/reference/commands/save-local). See [CDN publishing](#cdn-publishing) for per-file and per-command control. +When `true`, translated files are published to the General Translation CDN after [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload), or [`save-local`](/docs/cli/reference/commands/save-local). Lottie translations remain available through API and CLI downloads only; setting `publish` does not make `.lottie` files available from the CDN. See [CDN publishing](#cdn-publishing) for per-file and per-command control. ```json title="gt.config.json" { diff --git a/docs/en-US/cli/reference/formats/lottie-files.mdx b/docs/en-US/cli/reference/formats/lottie-files.mdx index 6814ffb0a..05d22e651 100644 --- a/docs/en-US/cli/reference/formats/lottie-files.mdx +++ b/docs/en-US/cli/reference/formats/lottie-files.mdx @@ -7,6 +7,16 @@ description: Translate dotLottie animation files with the General Translation CL The CLI translates text in binary dotLottie (`.lottie`) animation files and writes each result as a complete `.lottie` file. Lottie jobs include an asynchronous layout-processing phase, so they use the split stage-and-download workflow. +## Overview [#overview] + +| Topic | Description | +| --- | --- | +| [Configuration](#config) | Configure source and translated `.lottie` paths. | +| [Translation workflow](#workflow) | Stage asynchronous work and download completed animations. | +| [Expressions](#expressions) | Remove executable After Effects expressions before translation. | +| [Fonts](#fonts) | Upload fonts used during translated layout processing. | +| [Binary output](#binary) | Handle base64 transport and decoded `.lottie` files. | + ## Configuration [#config] Add a `lottie` entry under `files` with an `include` array of glob patterns. Use the `[locale]` placeholder so the CLI can find source animations and save translated files under each target locale. diff --git a/docs/en-US/platform/dashboard/guides/managing-billing.mdx b/docs/en-US/platform/dashboard/guides/managing-billing.mdx index 4c85520e3..9868bc387 100644 --- a/docs/en-US/platform/dashboard/guides/managing-billing.mdx +++ b/docs/en-US/platform/dashboard/guides/managing-billing.mdx @@ -52,7 +52,7 @@ Every billable workflow, including translations and Ask AI responses, deducts it ### Buying credits [#buying-credits] -Choose **Buy Credits** on the Billing page and enter an **Amount** to charge to your default payment method. The dialog shows the allowed range for your plan (the Starter minimum is $10). +Choose **Buy Credits** on the Billing page and enter an **Amount** to charge to your default payment method. The dialog shows the allowed range for your plan (the Starter minimum is $10). ### Auto-reload [#auto-reload] @@ -62,7 +62,7 @@ Auto-reload keeps your balance topped up automatically when your balance falls b - **Reload to** — the target balance to bring your credits back up to. - **Usage Limit** (optional) — a hard cap on total usage spend per billing period. -When usage reaches the limit you've set, billing is blocked even with auto-reload on. +When usage reaches the limit you've set, billing is blocked even with auto-reload on. ### Billing alerts @@ -86,7 +86,7 @@ What happens at $0 depends on auto-reload: Because Starter has no monthly fee, upgrading is simply adding a payment method. On the **Billing** page, choose **Manage Billing** and add a card and billing address. -Upgrading removes your rate limit and also unlocks features including: Locadex, team invites, auto-reload, the Translation Editor, version branching, and unlimited Projects. +Upgrading removes your rate limit and also unlocks features including: Locadex, team invites, auto-reload, the Translation Editor, version branching, and unlimited Projects. ### Upgrade to Enterprise [#to-enterprise] From 58892ae4a02b938da3bfe3511596000ea1318774 Mon Sep 17 00:00:00 2001 From: Brian Lou <69982825+brian-lou@users.noreply.github.com> Date: Mon, 3 Aug 2026 10:28:44 -0700 Subject: [PATCH 03/13] chore: update content (#437) --- docs/en-US/platform/openapi/openapi.yaml | 86 ++++++++++++++++- .../reference/project/create-project.mdx | 95 +++++++++++++++++++ .../openapi/reference/project/meta.json | 1 + 3 files changed, 177 insertions(+), 5 deletions(-) create mode 100644 docs/en-US/platform/openapi/reference/project/create-project.mdx diff --git a/docs/en-US/platform/openapi/openapi.yaml b/docs/en-US/platform/openapi/openapi.yaml index 823b09e5f..6f083c961 100644 --- a/docs/en-US/platform/openapi/openapi.yaml +++ b/docs/en-US/platform/openapi/openapi.yaml @@ -4,8 +4,8 @@ info: version: '2026-03-06.v1' description: > The public General Translation API. Use it to upload source content and - translated files, download translations, queue and translate content, manage - branches and tags, and read project and job status. + translated files, download translations, queue and translate content, create + projects, manage branches and tags, and read project and job status. Most endpoints operate on a single project and live under @@ -17,7 +17,9 @@ info: `Authorization: Bearer ` header. Project keys (`gtx-api-`, `gtx-dev-`) are bound to one project. Organization keys (`gtx-org-`) work across projects but must include the target project in - the `gt-project-id` header for project-scoped routes. + the `gt-project-id` header for project-scoped routes. Organization-scoped + routes, such as `POST /v2/projects`, derive the organization from the key and + do not use a `gt-project-id` header. contact: name: General Translation Support email: support@generaltranslation.com @@ -41,7 +43,7 @@ tags: - name: Tags description: Tag file versions. - name: Project - description: Read and update project information. + description: Create projects and read or update project information. - name: Jobs description: Read background job status. @@ -701,6 +703,79 @@ paths: '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } + /v2/projects: + post: + tags: [Project] + summary: Create a project + description: > + Create a project in the organization associated with an organization API + key. The key must have the `org:projects:create` permission. Project keys + cannot use this endpoint. + operationId: createProject + parameters: + - $ref: '#/components/parameters/GtApiVersion' + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + required: [name, defaultLocale] + properties: + name: + type: string + minLength: 1 + maxLength: 64 + description: > + Project name. Supports letters, numbers, spaces, dashes, + underscores, apostrophes, parentheses, and periods. + example: Customer Portal + defaultLocale: + type: string + description: Source locale for the project. + example: en-US + responses: + '201': + description: Project created. + content: + application/json: + schema: + type: object + required: [project] + properties: + project: + type: object + required: [id, name, orgId, defaultLocale] + properties: + id: { type: string, example: prj_abc123 } + name: { type: string, example: Customer Portal } + orgId: { type: string, example: org_abc123 } + defaultLocale: { type: string, example: en-US } + '400': { $ref: '#/components/responses/BadRequest' } + '401': { $ref: '#/components/responses/Unauthorized' } + '403': + description: > + The API key is not an organization key, lacks + `org:projects:create`, or is blocked by an access policy. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: The organization has reached its project limit. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '429': { $ref: '#/components/responses/RateLimited' } + '500': + description: The project could not be created. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /v2/project/info/{projectId}: get: tags: [Project] @@ -1186,7 +1261,8 @@ components: API key sent as a bearer token in the standard `Authorization: Bearer ` header. Use a project key (`gtx-api-`, `gtx-dev-`) or an organization key (`gtx-org-`). Organization keys must also send - `gt-project-id` on project-scoped routes. + `gt-project-id` on project-scoped routes. Organization-scoped routes + derive the organization from the key and do not use `gt-project-id`. parameters: GtApiVersion: diff --git a/docs/en-US/platform/openapi/reference/project/create-project.mdx b/docs/en-US/platform/openapi/reference/project/create-project.mdx new file mode 100644 index 000000000..459be2e44 --- /dev/null +++ b/docs/en-US/platform/openapi/reference/project/create-project.mdx @@ -0,0 +1,95 @@ +--- + +title: Create a Project +description: Create a General Translation Project with an Organization API key. API reference for Create a Project. + +method: POST +--- + +Creates a Project in the Organization associated with an Organization API key. Returns the new Project's ID, name, Organization ID, and normalized default locale. + +## Overview [#overview] + +```http +POST https://api2.gtx.dev/v2/projects +``` + +**Permission** `org:projects:create` · **Rate limit** Default (200/min) + +Use this endpoint to provision Projects from your own automation. Project API keys cannot create other Projects. + +## How it works [#how-it-works] + +- Authentication requires an Organization API key (`gtx-org-`) with `org:projects:create` permission. +- The Organization is derived from the API key. Do not send an Organization or Project ID in the request. +- The Project name is trimmed and validated. The default locale is validated and normalized, such as `en-us` to `en-US`. +- The new Project inherits the Organization's locale allowlist and AI provider settings. Existing Organization members are linked to it. +- The request returns `409` without creating a Project when the Organization has reached its Project limit. + +## Request [#request] + +### Headers + +| Header | Description | Required | +| --- | --- | --- | +| `x-gt-api-key` | Organization API key with `org:projects:create`. | Yes | +| `gt-api-version` | API version. | No | + +Do not send `x-gt-project-id`. This endpoint derives the Organization from the API key and creates a new Project within it. + +### Body + +**Content type** `application/json` + +| Field | Description | Type | Optional | Default | +| --- | --- | --- | --- | --- | +| `name` | Project name (1–64 characters). Supports letters, numbers, spaces, dashes, underscores, apostrophes, parentheses, and periods. | `string` | No | — | +| `defaultLocale` | Source locale for the Project. | `string` | No | — | + +Unknown fields are rejected. + +## Response [#response] + +**Status** `201 Created` + +| Field | Description | Type | +| --- | --- | --- | +| `project.id` | New Project ID. | `string` | +| `project.name` | Validated Project name. | `string` | +| `project.orgId` | Organization ID derived from the API key. | `string` | +| `project.defaultLocale` | Normalized source locale. | `string` | + +```json title="Response" +{ + "project": { + "id": "prj_...", + "name": "Customer Portal", + "orgId": "org_...", + "defaultLocale": "en-US" + } +} +``` + +## Errors [#errors] + +| Status | Cause | +| --- | --- | +| `400` | Invalid request body, Project name, or default locale. | +| `401` | Missing or invalid Organization API key. | +| `403` | The key is not an Organization key, lacks `org:projects:create`, or is blocked by an access policy. | +| `409` | The Organization has reached its Project limit. | +| `429` | Rate limit exceeded. | +| `500` | The Project could not be created. | + +## Example [#example] + +```bash +curl -X POST https://api2.gtx.dev/v2/projects \ + -H "x-gt-api-key: gtx-org-..." \ + -H "gt-api-version: 2026-03-06.v1" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Customer Portal", + "defaultLocale": "en-US" + }' +``` diff --git a/docs/en-US/platform/openapi/reference/project/meta.json b/docs/en-US/platform/openapi/reference/project/meta.json index 087bdd939..b3dca2bbe 100644 --- a/docs/en-US/platform/openapi/reference/project/meta.json +++ b/docs/en-US/platform/openapi/reference/project/meta.json @@ -2,6 +2,7 @@ "title": "Project", "description": "Browse OpenAPI Project pages.", "pages": [ + "./create-project", "./project-info", "./update-project", "./upload-assets", From a900616d85b52f8825b7b2b96c54f811d3bb5420 Mon Sep 17 00:00:00 2001 From: "cursor[bot]" <206951365+cursor[bot]@users.noreply.github.com> Date: Tue, 4 Aug 2026 10:14:13 -0700 Subject: [PATCH 04/13] fix: sync project API and usage docs (#438) Co-authored-by: Cursor Agent --- .../dashboard/guides/managing-billing.mdx | 20 +++++++++++++++---- .../platform/dashboard/reference/api-keys.mdx | 7 ++++--- .../reference/organization-settings.mdx | 10 ++++++++-- docs/en-US/platform/openapi/openapi.yaml | 11 +++++++--- docs/en-US/platform/openapi/overview.mdx | 12 ++++++----- .../reference/project/create-project.mdx | 12 ++++++----- 6 files changed, 50 insertions(+), 22 deletions(-) diff --git a/docs/en-US/platform/dashboard/guides/managing-billing.mdx b/docs/en-US/platform/dashboard/guides/managing-billing.mdx index 9868bc387..3c8cfab0b 100644 --- a/docs/en-US/platform/dashboard/guides/managing-billing.mdx +++ b/docs/en-US/platform/dashboard/guides/managing-billing.mdx @@ -11,9 +11,7 @@ related: --- -This guide covers General Translation's usage-based billing, pricing, credits, and auto-reload. - -*Note: Manage everything from the **Billing** page for your Organization in the Dashboard.* +Usage records and spend estimates live on **Usage**. Plans, credit balances, reload settings, and invoices live on **Billing** for your Organization. ## Plans [#plans] @@ -28,7 +26,13 @@ Each free Organization gets 5M free platform credits to start. You will be rate- You pay per workflow: cost is based on the number of input tokens, workflow type (build time, runtime, or development), file format, and any context you provide. Google Slides also has a separate **Layout Processing** charge for each completed slide. -Review consumption under **Organization > Usage > Translations**. Filter by Project and time range, compare usage by target locale or service type, and inspect each transaction's input tokens, output tokens, and cost. +Review consumption under **Organization > Usage**. Select **Tokens**, **Agent**, or **Cost** if you can view billing. The page opens to the current billing period when one is available, or the last 30 days otherwise. You can also select the last 7 days or a custom date range of up to 100 days. + +- **Tokens** shows total and daily input tokens with breakdowns by target locale and service type. +- **Agent** shows total and daily Organization-wide LCU usage. +- **Cost** shows Organization-wide spend after contract pricing, custom discounts, and applied credits. Amounts can change until the billing period is invoiced. + +The page also lists recent translation records with input and output token counts and recent Agent workflow records with trace IDs. When the Organization has multiple Projects, the Project selector filters token metrics and translation records; Agent and Cost totals remain Organization-wide. ### How usage is metered [#usage-metering] @@ -40,6 +44,14 @@ Review consumption under **Organization > Usage > Translations**. Filter by Proj See the [usage rates](https://generaltranslation.com/pricing/usage) page for current rates and calculation examples. +## Invoice history [#invoices] + +When invoices are available, the **Billing** page shows each invoice's date, description, status, and amount. Choose **Breakdown** to review line items and quantities, or **View** to open the hosted invoice when one is available. + + + **Enterprise-managed Organizations:** Cost and invoice data are managed at Enterprise scope. Open **Enterprise > Billing** to review them. + + ## How the credit balance works [#credits] Your **credit balance** is a prepaid wallet for platform usage, shown on the **Billing** page and denominated in dollars ($1 = 1M credits). The balance is split into buckets: diff --git a/docs/en-US/platform/dashboard/reference/api-keys.mdx b/docs/en-US/platform/dashboard/reference/api-keys.mdx index f8a2b1878..70205bb52 100644 --- a/docs/en-US/platform/dashboard/reference/api-keys.mdx +++ b/docs/en-US/platform/dashboard/reference/api-keys.mdx @@ -18,19 +18,20 @@ Organization keys and Project keys have different creation flows. Project keys a ## Create Organization keys [#create-organization-keys] -Create Organization keys from **Organization > API Keys**. Organization keys use the `gtx-org-` prefix and can be configured with a custom permission set. +Create Organization keys from **Organization > API Keys**. Organization keys use the `gtx-org-` prefix and can be configured with a custom permission set. Permissions are configured per resource. `Write` includes `Read`. | Resource | Read | Write or enabled | | ----------------------- | ------------------------------------- | ----------------------------------------------------- | +| **Project creation** | Not applicable | Create new Projects in the Organization | | **Files** | Read Project files and translations | Upload source content and write translated files | | **Context** | Read Project and Organization context | Manage context groups, glossary, and directives | | **Runtime translation** | Not applicable | Translate content on demand | | **Translation queue** | Not applicable | Queue file translation jobs for background processing | | **Project settings** | Not applicable | Update Project settings such as the default locale | -Grant each key only the permissions it needs. +Enable **Project creation** for automation that calls the [Create a Project](/docs/platform/openapi/reference/project/create-project) endpoint. Grant each key only the permissions it needs. ## Create Project keys [#create-project-keys] @@ -50,7 +51,7 @@ GT_PROJECT_ID=... ``` ## Manage keys [#manage-keys] -Use descriptive names so keys are easy to identify later. +Use descriptive names so keys are easy to identify later. Open the key list for the Project or Organization to review existing keys. The key list shows: diff --git a/docs/en-US/platform/dashboard/reference/organization-settings.mdx b/docs/en-US/platform/dashboard/reference/organization-settings.mdx index 8b52e21dc..5b3ea8c64 100644 --- a/docs/en-US/platform/dashboard/reference/organization-settings.mdx +++ b/docs/en-US/platform/dashboard/reference/organization-settings.mdx @@ -31,9 +31,15 @@ For a detailed breakdown, see [roles and permissions](/docs/platform/dashboard/r ## Usage and billing [#usage-billing] -Open **Organization > Usage > Translations** to filter usage by Project and time range. The page shows daily consumption, breakdowns by target locale and service type, and individual translation records with separate input and output token counts. +Open **Organization > Usage** to switch among **Tokens**, **Agent**, and **Cost** if your role can view billing. The page opens to the current billing period when one is available, or the last 30 days otherwise. You can also select the last 7 days or a custom range of up to 100 days. -Open **Organization > Usage > Locadex** to see Locadex usage. Manage your plan, billing, and credit balance from **Organization > Billing**. [Contact us](https://generaltranslation.com/en-US/enterprise/contact) if you're interested in Enterprise plans for larger teams with complex localization needs. +- **Tokens** shows total and daily input-token usage with target-locale and service-type breakdowns. +- **Agent** shows total and daily Organization-wide LCU usage. +- **Cost** shows Organization-wide spend after contract pricing, custom discounts, and applied credits. Amounts can change until the billing period is invoiced. + +The page also lists recent translation records with input and output token counts and recent Agent workflow records with trace IDs. When the Organization has multiple Projects, the Project selector filters token metrics and translation records; Agent and Cost totals remain Organization-wide. + +Manage an Organization-owned plan, credit balance, and invoices from **Organization > Billing**. Expand an invoice to review its line items and quantities. Enterprise-managed Organizations use **Enterprise > Billing** instead. [Contact us](https://generaltranslation.com/en-US/enterprise/contact) if you're interested in Enterprise plans for larger teams with complex localization needs. ## Connections [#connections] diff --git a/docs/en-US/platform/openapi/openapi.yaml b/docs/en-US/platform/openapi/openapi.yaml index 6f083c961..3445d4089 100644 --- a/docs/en-US/platform/openapi/openapi.yaml +++ b/docs/en-US/platform/openapi/openapi.yaml @@ -753,11 +753,16 @@ paths: orgId: { type: string, example: org_abc123 } defaultLocale: { type: string, example: en-US } '400': { $ref: '#/components/responses/BadRequest' } - '401': { $ref: '#/components/responses/Unauthorized' } + '401': + description: Missing, invalid, or non-organization API key. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' '403': description: > - The API key is not an organization key, lacks - `org:projects:create`, or is blocked by an access policy. + The API key lacks `org:projects:create` or is blocked by an access + policy. content: application/json: schema: diff --git a/docs/en-US/platform/openapi/overview.mdx b/docs/en-US/platform/openapi/overview.mdx index 353701b5a..3ef7bfce4 100644 --- a/docs/en-US/platform/openapi/overview.mdx +++ b/docs/en-US/platform/openapi/overview.mdx @@ -9,12 +9,13 @@ related: - /docs/platform/openapi/reference/files/upload-source - /docs/platform/openapi/reference/context/generate-context - /docs/platform/openapi/reference/translation/translate-runtime - - /docs/platform/openapi/reference/project/project-info + - /docs/platform/openapi/reference/project/create-project + --- Use the General Translation API to build custom automation workflows. -The SDK and CLI handle most API calls for you. Call the API directly when you need to upload files, queue translation jobs, download translations, manage branches and tags, or inspect Project and job status from your own system. +The SDK and CLI handle most API calls for you. Call the API directly when you need to create Projects, upload files, queue translation jobs, download translations, manage branches and tags, or inspect Project and job status from your own system. The OpenAPI spec defines these endpoints in machine-readable format. @@ -40,7 +41,7 @@ Use the correct key type: - **Project (development)** with prefix `gtx-dev-`: for local and preview use, rejected by production-only endpoints - **Project (production)** with prefix `gtx-api-`: bound to one Project -- **Organization** with prefix `gtx-org-`: works across Projects. When using an Organization key on Project-scoped endpoints, must send `x-gt-project-id`. +- **Organization** with prefix `gtx-org-`: works across Projects. When using an Organization key on Project-scoped endpoints, send `x-gt-project-id`. Organization-scoped endpoints, such as `POST /v2/projects`, derive the Organization from the key. See [API keys](/docs/platform/dashboard/reference/api-keys) for how to create and scope API keys. @@ -50,6 +51,7 @@ Each endpoint requires a permission on the API key. Organization keys configure Common permissions: +- `org:projects:create` for creating Projects with `POST /v2/projects`. - `project:files:read` for downloading files, reading file info, translation status, branch info, orphaned files, Project info, and job info. - `project:files:write` for uploading files and translations, diffs, publishing, creating branches and tags, and moving files. - `project:translations:enqueue` for queuing files for translation. @@ -62,7 +64,7 @@ Common permissions: ### Versioning -Send the optional `gt-api-version` header to pin a response format. +Send the optional `gt-api-version` header to pin a response format. ```bash -H "gt-api-version: 2026-03-06.v1" @@ -77,7 +79,7 @@ Requests are rate limited per API key or client IP over a 60-second window. Limi - **Heavy:** 30 requests/minute for queueing translations. - **Medium:** 120 requests/minute for uploads, diffs, context, moves, and orphaned files. - **Light:** 300 requests/minute for file downloads. -- **Default:** 200 requests/minute for publish, branches, tags, Project info, job info, file info, translation status, and runtime translation. +- **Default:** 200 requests/minute for Project creation, publish, branches, tags, Project info, job info, file info, translation status, and runtime translation. Exceeding a limit returns `429`. Organization token quotas return `402` from `POST /v2/translate`. diff --git a/docs/en-US/platform/openapi/reference/project/create-project.mdx b/docs/en-US/platform/openapi/reference/project/create-project.mdx index 459be2e44..611548505 100644 --- a/docs/en-US/platform/openapi/reference/project/create-project.mdx +++ b/docs/en-US/platform/openapi/reference/project/create-project.mdx @@ -4,6 +4,7 @@ title: Create a Project description: Create a General Translation Project with an Organization API key. API reference for Create a Project. method: POST + --- Creates a Project in the Organization associated with an Organization API key. Returns the new Project's ID, name, Organization ID, and normalized default locale. @@ -20,10 +21,11 @@ Use this endpoint to provision Projects from your own automation. Project API ke ## How it works [#how-it-works] -- Authentication requires an Organization API key (`gtx-org-`) with `org:projects:create` permission. +- Authentication requires an [Organization API key](/docs/platform/dashboard/reference/api-keys#create-organization-keys) (`gtx-org-`) with `org:projects:create` permission. - The Organization is derived from the API key. Do not send an Organization or Project ID in the request. - The Project name is trimmed and validated. The default locale is validated and normalized, such as `en-us` to `en-US`. -- The new Project inherits the Organization's locale allowlist and AI provider settings. Existing Organization members are linked to it. +- The new Project copies the Organization's AI provider settings. Its locale allowlist copies the Organization allowlist except for locales in the same dialect as the default locale; it starts empty when the Organization has no allowlist. +- Existing Organization members are linked to the new Project. - The request returns `409` without creating a Project when the Organization has reached its Project limit. ## Request [#request] @@ -74,9 +76,9 @@ Unknown fields are rejected. | Status | Cause | | --- | --- | -| `400` | Invalid request body, Project name, or default locale. | -| `401` | Missing or invalid Organization API key. | -| `403` | The key is not an Organization key, lacks `org:projects:create`, or is blocked by an access policy. | +| `400` | Invalid API version, request body, Project name, or default locale. | +| `401` | Missing, invalid, or non-Organization API key. | +| `403` | The key lacks `org:projects:create` or is blocked by an access policy. | | `409` | The Organization has reached its Project limit. | | `429` | Rate limit exceeded. | | `500` | The Project could not be created. | From 563c0682d0a0a29080c5f30374914ed415195fae Mon Sep 17 00:00:00 2001 From: Archie McKenzie <90429137+archie-mckenzie@users.noreply.github.com> Date: Tue, 4 Aug 2026 22:07:50 -0700 Subject: [PATCH 05/13] Update overview.mdx (#441) --- docs/en-US/react/overview.mdx | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/en-US/react/overview.mdx b/docs/en-US/react/overview.mdx index d8dcb9de6..3dfd56fbd 100644 --- a/docs/en-US/react/overview.mdx +++ b/docs/en-US/react/overview.mdx @@ -1,35 +1,33 @@ --- title: Overview -description: Learn about the General Translation React ecosystem, how its shared translation model works, and which quickstart to follow for your framework. +description: Learn about General Translation React libraries and which quickstart to follow for your framework. --- -General Translation internationalizes the React ecosystem through one shared API. The same components, hooks, and configuration work whether you build a React single-page app, a Next.js app, a TanStack Start app, or a React Native app. +General Translation internationalization libraries for React apps share components, hooks, and configurations across React SPA, Next.js App Router, Next.js Pages Router, TanStack Start, and React Native. This is the landing page for the React section. Read on to understand the ecosystem and pick your framework, then follow the matching quickstart. ## The React ecosystem [#ecosystem] -Each framework has its own package, but all of them expose the same translation API: +Each framework has its own package: - `gt-react` — for server-rendered React apps and single-page apps (SPAs), such as Vite or Create React App. See the [React Quickstart](/docs/react/react-quickstart) or [React SPA Quickstart](/docs/react/react-spa-quickstart). - `gt-next` — for Next.js App Router and Pages Router apps. See the [Next.js App Router Quickstart](/docs/react/nextjs-quickstart) or [Next.js Pages Router Quickstart](/docs/react/nextjs-pages-router-quickstart). - `gt-tanstack-start` — for TanStack Start apps. See the [TanStack Start Quickstart](/docs/react/tanstack-start-quickstart). - `gt-react-native` — for React Native apps, including Expo and the bare React Native CLI. See the [React Native Quickstart](/docs/react/react-native-quickstart). -*Note:* `gt-tanstack-start` *and* `gt-react-native` *are experimental and not yet recommended for production.* - ## Shared translation model [#shared-model] -Because every package is built on the same core, you learn the model once and reuse it everywhere. The pieces are: +Because every React i18n library is built around the same core component and hooks, there's only one interface to learn. The important parts are: -- **The** [``](/docs/react/reference/components/t) **component.** Wrap any JSX in [``](/docs/react/reference/components/t) to translate it in place, including nested elements and formatting. [``](/docs/react/reference/components/t) translates its contents as a single unit. -- **The** [`useGT`](/docs/react/reference/hooks/use-gt) **hook.** Translate standalone strings — placeholders, `aria-label` values, alt text — with the function it returns. Call it as `const gt = useGT();`, then `gt('Hello, world!')`. In async App Router components, use [`getGT`](/docs/react/nextjs/reference/functions/get-gt) from `gt-next/server`. -- **The** [`GTProvider`](/docs/react/reference/components/gt-provider) **component.** Wrap your app so components can access translations and the active locale. How you supply translations to it differs slightly per framework, which is why each has its own quickstart. -- **The** `gt` **CLI.** The `gt` package generates and downloads translations. Its [`gt.config.json`](/docs/cli/reference/config) file declares your `defaultLocale`, target `locales`, and translation output paths. Run [`npx gt translate`](/docs/cli/reference/commands/translate) to translate your project through the General Translation API. +- [``](/docs/react/reference/components/t) **component.** Wrap any JSX in [``](/docs/react/reference/components/t) to translate it in place, including nested elements and formatting. [``](/docs/react/reference/components/t) translates its contents as a single unit. +- [`useGT`](/docs/react/reference/hooks/use-gt) **hook.** Translate standalone strings — placeholders, `aria-label` values, alt text — with the function it returns. Call it as `const gt = useGT();`, then `gt('Hello, world!')`. In async App Router components, use [`getGT`](/docs/react/nextjs/reference/functions/get-gt) from `gt-next/server`. +- [`GTProvider`](/docs/react/reference/components/gt-provider) **component.** Wrap your app so components can access translations and the active locale. How you supply translations to it differs slightly per framework, which is why each has its own quickstart. +- `gt` **CLI.** The `gt` package generates and downloads translations. Its [`gt.config.json`](/docs/cli/reference/config) file declares your `defaultLocale`, target `locales`, and translation output paths. Run [`npx gt translate`](/docs/cli/reference/commands/translate) to translate your project through the General Translation API. -Variable components ([``](/docs/react/reference/components/var), [``](/docs/react/reference/components/num), [``](/docs/react/reference/components/currency), [``](/docs/react/reference/components/datetime)), the [``](/docs/react/reference/components/plural) and [``](/docs/react/reference/components/branch) components, and the locale hooks are shared across all frameworks too. +Variable components ([``](/docs/react/reference/components/var), [``](/docs/react/reference/components/num), [``](/docs/react/reference/components/currency), [``](/docs/react/reference/components/datetime)), the [``](/docs/react/reference/components/plural) and [``](/docs/react/reference/components/derive) components, and helper hooks are shared across all frameworks too. ## Choose your framework [#frameworks] From 648f9bb48d458be99760ff71b151a09ee8065bf5 Mon Sep 17 00:00:00 2001 From: "cursor[bot]" <206951365+cursor[bot]@users.noreply.github.com> Date: Wed, 5 Aug 2026 09:31:23 -0700 Subject: [PATCH 06/13] docs: sync shipped CLI, TanStack, and CDN behavior (#442) Co-authored-by: Cursor Agent --- devlog/en-US/local-edits.mdx | 2 +- docs/en-US/cli/guides/configuring.mdx | 4 +++- docs/en-US/cli/guides/managing-translations.mdx | 2 +- docs/en-US/cli/quickstart.mdx | 8 +++++--- docs/en-US/cli/reference/commands/configure.mdx | 12 +++++++----- docs/en-US/cli/reference/commands/download.mdx | 2 +- docs/en-US/cli/reference/commands/init.mdx | 8 +++++--- docs/en-US/cli/reference/commands/save-local.mdx | 2 +- docs/en-US/cli/reference/commands/translate.mdx | 16 ++++++++++++---- .../dashboard/guides/managing-billing.mdx | 2 +- .../dashboard/guides/reviewing-translations.mdx | 2 ++ .../platform/dashboard/reference/api-keys.mdx | 4 ++-- .../reference/organization-settings.mdx | 4 ++-- docs/en-US/platform/openapi/openapi.yaml | 14 +++++++++++--- docs/en-US/platform/openapi/overview.mdx | 2 +- .../openapi/reference/project/create-project.mdx | 11 +++++++---- .../openapi/reference/project/update-project.mdx | 10 +++++++--- .../react/(frameworks)/tanstack-start/index.mdx | 2 +- .../reference/functions/gt-middleware.mdx | 14 ++++++++------ .../react/(frameworks)/tanstack-start/setup.mdx | 4 +--- .../react/guides/developing-spa-translations.mdx | 2 +- .../react/nextjs-pages-router-quickstart.mdx | 2 +- docs/en-US/react/nextjs-quickstart.mdx | 2 +- docs/en-US/react/overview.mdx | 12 +++++++----- docs/en-US/react/react-quickstart.mdx | 2 +- docs/en-US/react/react-spa-quickstart.mdx | 6 +----- docs/en-US/react/tanstack-start-quickstart.mdx | 4 +--- 27 files changed, 92 insertions(+), 63 deletions(-) diff --git a/devlog/en-US/local-edits.mdx b/devlog/en-US/local-edits.mdx index 3a20138dd..f7d54689c 100644 --- a/devlog/en-US/local-edits.mdx +++ b/devlog/en-US/local-edits.mdx @@ -10,7 +10,7 @@ tags: ['gtx-cli', 'save-local', 'translate'] In **gtx-cli 2.4.0**, we've added a new way to save your local translation edits directly from the CLI. This means you can now make translation changes locally, persist them, and keep everything in sync with your project without touching the dashboard. -_Version note: This post describes the 2.4.0 behavior. In `gt` and `gtx-cli` 2.16.0, pass `--save-local` to [`translate`](/docs/cli/reference/commands/translate) to run the save step._ +_Version note: This post describes the 2.4.0 behavior. In `gt` and `gtx-cli` 2.16.1 and later, [`translate`](/docs/cli/reference/commands/translate) runs the save step by default; pass `--no-save-local` to skip it._ --- diff --git a/docs/en-US/cli/guides/configuring.mdx b/docs/en-US/cli/guides/configuring.mdx index 415f53467..66f491b55 100644 --- a/docs/en-US/cli/guides/configuring.mdx +++ b/docs/en-US/cli/guides/configuring.mdx @@ -21,12 +21,14 @@ You can create `gt.config.json` three ways. Pick whichever fits your workflow. ### a) Run the full setup wizard -Run [`gt init`](/docs/cli/reference/commands/init) to detect your framework, install dependencies, create the config file, and generate credentials in one pass. +Run [`gt init`](/docs/cli/reference/commands/init) to detect your framework, install dependencies, create the config file, and generate credentials when needed. ```bash npx gt init ``` +In a monorepo, run the command from the app you want to localize, not the workspace root. For Vite React apps, the wizard installs `gt-react`, configures [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) before the existing app entry, and sets up local or CDN translation loading. + ### b) Create only the config file Run [`gt configure`](/docs/cli/reference/commands/configure) to create `gt.config.json` without installing dependencies or changing your framework setup. diff --git a/docs/en-US/cli/guides/managing-translations.mdx b/docs/en-US/cli/guides/managing-translations.mdx index 8a62fd4a1..64aaf984c 100644 --- a/docs/en-US/cli/guides/managing-translations.mdx +++ b/docs/en-US/cli/guides/managing-translations.mdx @@ -65,4 +65,4 @@ When you or a translator edit downloaded translation files by hand, use [`gt sav npx gt save-local ``` -The command compares your local files against the last downloaded versions, computes a diff for anything that changed, and submits it. It does not enqueue any new translations. To capture local edits as part of a translation run instead, pass `--save-local` to [`translate`](/docs/cli/reference/commands/translate). +The command compares your local files against the last downloaded versions, computes a diff for anything that changed, and submits it. It does not enqueue any new translations. [`gt translate`](/docs/cli/reference/commands/translate) performs this save step by default before it enqueues new work; pass `--no-save-local` to skip it for a run. diff --git a/docs/en-US/cli/quickstart.mdx b/docs/en-US/cli/quickstart.mdx index 5b1832553..17bd17e43 100644 --- a/docs/en-US/cli/quickstart.mdx +++ b/docs/en-US/cli/quickstart.mdx @@ -68,19 +68,21 @@ Install the CLI as a dev dependency. ### 2. Configure your project -Run the setup wizard to detect your framework, create a `gt.config.json`, and generate credentials. +Run the setup wizard to detect your framework, create a `gt.config.json`, and generate credentials when the selected setup needs them. ```bash npx gt init ``` +In a monorepo, run the command from the app you want to localize. The wizard stops without changing files when you run it from the workspace root. + [`gt init`](/docs/cli/reference/commands/init) is an interactive wizard and needs a terminal. In CI or another non-interactive shell it may wait for input, fail validation, or exit early without creating `gt.config.json` or writing credentials. For those environments, use [Non-interactive setup for CI](#ci-setup). -The wizard sets your default locale and target locales, chooses where translations are stored, and writes your API key and Project ID to `.env.local`. See [Configuring the CLI](/docs/cli/guides/configuring) to set this up in detail, or [`gt init`](/docs/cli/reference/commands/init) for the full command. +The wizard sets your default locale and target locales and chooses where translations are stored. When the selected setup needs credentials, it can write your API key and Project ID to `.env.local`. See [Configuring the CLI](/docs/cli/guides/configuring) to set this up in detail, or [`gt init`](/docs/cli/reference/commands/init) for the full command. -*Note: You should now have a `gt.config.json` at your project root and a `.env.local` file containing `GT_API_KEY` and `GT_PROJECT_ID`.* +*Note: You should now have a `gt.config.json` at your project root. If the wizard generated credentials, `.env.local` contains `GT_API_KEY` and `GT_PROJECT_ID`. The bundled-local Vite setup skips credentials, so add them in the next step before translating.* ### 3. Add your production API key diff --git a/docs/en-US/cli/reference/commands/configure.mdx b/docs/en-US/cli/reference/commands/configure.mdx index e96b22cd1..48c837370 100644 --- a/docs/en-US/cli/reference/commands/configure.mdx +++ b/docs/en-US/cli/reference/commands/configure.mdx @@ -5,9 +5,9 @@ description: Create a General Translation gt.config.json file. API reference for --- -Creates a `gt.config.json` file at the root of your project. Unlike [`gt init`](/docs/cli/reference/commands/init), it does not install dependencies, change your framework setup, or generate credentials — it only writes configuration. +Creates or updates a `gt.config.json` file at the root of your project. Unlike [`gt init`](/docs/cli/reference/commands/init), it does not install dependencies, change your framework setup, or generate credentials — it only writes configuration. -The command prompts for your default locale, target locales, and the file types you want to translate. For a walkthrough of the resulting file, see [Configuring the CLI](/docs/cli/guides/configuring). +The command prompts for missing locale settings and the file types you want to translate. It preserves valid existing locale and file settings. For a walkthrough of the resulting file, see [Configuring the CLI](/docs/cli/guides/configuring). ```bash npx gt configure @@ -15,8 +15,8 @@ npx gt configure ## How it works [#how-it-works] -1. Prompts for your default locale, target locales, and the file types you want to translate. -2. Writes a `gt.config.json` file at the root of your project containing your `defaultLocale`, `locales`, and a `files` object. +1. Reads existing configuration and prompts for missing default locale, target locales, and file types. +2. Writes `defaultLocale`, `locales`, and a `files` object without replacing unrelated file settings. `configure` is the configuration step of the [`gt init`](/docs/cli/reference/commands/init) wizard. Run it on its own to create the config file without touching dependencies, framework setup, or credentials. @@ -33,4 +33,6 @@ npx gt configure ## Other notes [#notes] -The generated `gt.config.json` includes your `defaultLocale`, `locales`, and a `files` object describing the content to translate. See the [configuration reference](/docs/cli/reference/config) for every available option. +- In a monorepo, run `configure` from the specific app directory. The command stops without changing files when the current directory is a workspace root with `pnpm-workspace.yaml` or a `workspaces` field. +- Automatic configuration is not available for Electron applications. +- The generated `gt.config.json` includes your `defaultLocale`, `locales`, and a `files` object describing the content to translate. See the [configuration reference](/docs/cli/reference/config) for every available option. diff --git a/docs/en-US/cli/reference/commands/download.mdx b/docs/en-US/cli/reference/commands/download.mdx index f89748358..fe726475e 100644 --- a/docs/en-US/cli/reference/commands/download.mdx +++ b/docs/en-US/cli/reference/commands/download.mdx @@ -38,7 +38,7 @@ Files that are still processing are skipped. Re-run `gt download` to fetch them | `--dry-run` | Parse and validate without calling the API. | `boolean` | Yes | `false` | | `--force` | Invalidate cached translations and re-translate. | `boolean` | Yes | `false` | | `--force-download` | Overwrite local files, bypassing `gt-lock.json` checks. | `boolean` | Yes | `false` | -| `--save-local` | Accepted by the shared flag parser, but does not save edits during a download-only run. | `boolean` | Yes | `false` | +| `--save-local, --no-save-local` | Accepted by the shared flag parser, but does not save edits during a download-only run. | `boolean` | Yes | `true` | | `--publish` | Publish translations to the CDN. | `boolean` | Yes | `false` | | `--enable-branching` | Enable branch-based tracking. | `boolean` | Yes | — | | `--branch ` | Branch name instead of auto-detecting. | `string` | Yes | — | diff --git a/docs/en-US/cli/reference/commands/init.mdx b/docs/en-US/cli/reference/commands/init.mdx index e692d2970..6ae299006 100644 --- a/docs/en-US/cli/reference/commands/init.mdx +++ b/docs/en-US/cli/reference/commands/init.mdx @@ -16,9 +16,9 @@ npx gt init ## How it works [#how-it-works] 1. Detects your framework. For a Next.js App Router or Mintlify project, it offers to connect the [Locadex](/docs/platform/locadex/quickstart) AI agent instead. -2. For a React-based project, optionally installs `gt-react` or `gt-next` and adds the [`GTProvider`](/docs/react/reference/components/gt-provider) (experimental). -3. Prompts for your default locale and target locales and creates `gt.config.json`. For local storage, it also creates a [`loadTranslations`](/docs/react/reference/functions/load-translations) file. -4. Installs `gt` as a dev dependency if it is not already installed. +2. For a React-based project, optionally installs `gt-react` or `gt-next` and configures the framework (experimental). Vite apps get an [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) bootstrap that runs before the existing app entry; other supported React apps use [`GTProvider`](/docs/react/reference/components/gt-provider). +3. Prompts for any missing default and target locales and creates or updates `gt.config.json`. Existing locale and file settings are preserved. For local Vite storage, it also creates a [`loadTranslations`](/docs/react/reference/functions/load-translations) file and empty target-locale files. +4. Installs `gt` as a dev dependency when the configured workflow needs a persistent CLI installation. Vite framework setup does not add `gt`; continue to run it with `npx gt`. 5. Optionally generates an API key and Project ID and writes them to `.env.local`. *Note: The React setup step is experimental and may not work for every project. Review the changes it makes.* @@ -43,5 +43,7 @@ npx gt ## Other notes [#notes] - `init` runs the same steps as [`gt configure`](/docs/cli/reference/commands/configure) and [`gt auth`](/docs/cli/reference/commands/auth) together, plus the experimental React setup wizard. Run either command on its own to repeat just that step. It does not run [`gt setup`](/docs/cli/reference/commands/setup), which uploads your source files. +- In a monorepo, run `init` from the specific app directory. The command stops without changing files when the current directory is a workspace root with `pnpm-workspace.yaml` or a `workspaces` field. +- Automatic setup is not available for Electron applications. - The API key and Project ID are not required to use `gt-react` or `gt-next` — they are only needed to call the General Translation API. - If the experimental React setup does not work for your project, set it up manually using the [React](/docs/react/react-quickstart) docs. diff --git a/docs/en-US/cli/reference/commands/save-local.mdx b/docs/en-US/cli/reference/commands/save-local.mdx index bbaec4dc9..e88f6066c 100644 --- a/docs/en-US/cli/reference/commands/save-local.mdx +++ b/docs/en-US/cli/reference/commands/save-local.mdx @@ -45,5 +45,5 @@ npx gt save-local --publish ## Other notes [#notes] - The CLI tracks downloaded translations in a lock file and only processes files that changed since the last download. -- To save local edits and translate in one step, pass `--save-local` to [`gt translate`](/docs/cli/reference/commands/translate). +- [`gt translate`](/docs/cli/reference/commands/translate) saves local edits before enqueuing by default. Use `gt save-local` when you want to sync edits without starting new translation work. - Never store your API key in `gt.config.json`. The CLI reads `GT_API_KEY` from the environment automatically. diff --git a/docs/en-US/cli/reference/commands/translate.mdx b/docs/en-US/cli/reference/commands/translate.mdx index a2dcbc0c7..17308a070 100644 --- a/docs/en-US/cli/reference/commands/translate.mdx +++ b/docs/en-US/cli/reference/commands/translate.mdx @@ -20,10 +20,11 @@ npx gt translate 1. Reads `gt.config.json` to determine the target locales, the files to translate, and their output paths. 2. For `gt-next`, `gt-react`, `gt-react-native`, and `gt-tanstack-start` projects, scans your `src` globs for inline content — [``](/docs/react/reference/components/t) components and [`useGT`](/docs/react/reference/hooks/use-gt) calls — and includes your dictionary file. 3. Auto-detects a third-party i18n library from `package.json` — `next-intl` or `i18next` (with `i18next-icu` support) — and translates its JSON files while respecting that library's syntax. -4. Stages the collected content and downloads the results in one step. Internally this is [`gt stage`](/docs/cli/reference/commands/stage) followed by [`gt download`](/docs/cli/reference/commands/download); use the split commands to run those parts separately. Because Lottie layout processing is asynchronous, a project with `.lottie` files exits here when `stageTranslations` is `false` and directs you to the split flow. -5. Saves translations to your codebase, and to the CDN when `--publish` or the [`publish`](/docs/cli/reference/config#publish) config key is set. +4. Detects local edits to previously downloaded translations and saves them to the platform. Pass `--no-save-local` to skip this step. +5. Stages the collected content and downloads the results in one step. Internally this is [`gt stage`](/docs/cli/reference/commands/stage) followed by [`gt download`](/docs/cli/reference/commands/download); use the split commands to run those parts separately. Because Lottie layout processing is asynchronous, a project with `.lottie` files exits here when `stageTranslations` is `false` and directs you to the split flow. +6. Saves translations to your codebase, and to the CDN when `--publish` or the [`publish`](/docs/cli/reference/config#publish) config key is set. -By default, the CLI does not overwrite local translation changes unless the source content has changed. Use `--force` to re-translate everything, or `--force-download` to re-download without re-translating. +By default, the CLI syncs local translation edits before starting new work and does not overwrite them unless the source content has changed. Use `--force` to re-translate everything, or `--force-download` to re-download without re-translating. ## Flags [#flags] @@ -39,7 +40,7 @@ By default, the CLI does not overwrite local translation changes unless the sour | `--dry-run` | Parse and validate without calling the API. | `boolean` | Yes | `false` | | `--force` | Re-translate all content, overwriting existing translations. | `boolean` | Yes | `false` | | `--force-download` | Re-download all translations, overwriting local changes. | `boolean` | Yes | `false` | -| `--save-local` | Save local edits before enqueuing. | `boolean` | Yes | `false` | +| `--save-local, --no-save-local` | Enable or disable saving local edits before enqueuing. | `boolean` | Yes | `true` | | `--publish` | Publish translations to the CDN. | `boolean` | Yes | `false` | | `--enable-branching` | Enable branch-based tracking. | `boolean` | Yes | `false` | | `--branch ` | Branch name instead of auto-detecting. | `string` | Yes | — | @@ -92,9 +93,16 @@ npx gt translate --tag v2.1.0 -m "Added checkout page translations" - **Content sources:** the CLI scans `src`, `app`, `pages`, and `components` by default. Override with `--src` or the [`src`](/docs/cli/reference/config#src) config key. - **Dictionary:** when `--dictionary` is not set, the CLI looks for `dictionary.[json|ts|js]` in `./src` and `./`. +- **Local edits:** local edits are saved before translation by default. Pass `--no-save-local` to skip the save step for a run. - **Overwriting:** `--force` overwrites all existing translations and bills for new ones; `--force-download` overwrites local edits with the latest translations without re-translating. - **Lottie:** translate animations with [`gt stage`](/docs/cli/reference/commands/stage), then re-run [`gt download`](/docs/cli/reference/commands/download) until every locale is ready. See the [Lottie format reference](/docs/cli/reference/formats/lottie-files). - **Tagging:** tagging is non-blocking — if tag creation fails, the run continues. Pass `--tag` with no value to use the current git commit hash and message. - **Publishing:** enable the CDN in your Project settings before using `--publish`. If the CDN is not enabled, the run translates successfully but the publish step fails with a warning. - **Branching:** pass `--enable-branching` to track translations per git branch. See [Tracking translations by branch](/docs/cli/guides/branching). - **Security:** never store your API key in `gt.config.json`. The CLI reads `GT_API_KEY` and `GT_PROJECT_ID` from the environment automatically. + +### Version history + +| Version | Changes | +| --- | --- | +| `2.16.1` | Local edits are saved by default; `--no-save-local` opts out. | diff --git a/docs/en-US/platform/dashboard/guides/managing-billing.mdx b/docs/en-US/platform/dashboard/guides/managing-billing.mdx index 3c8cfab0b..2188bfbd6 100644 --- a/docs/en-US/platform/dashboard/guides/managing-billing.mdx +++ b/docs/en-US/platform/dashboard/guides/managing-billing.mdx @@ -26,7 +26,7 @@ Each free Organization gets 5M free platform credits to start. You will be rate- You pay per workflow: cost is based on the number of input tokens, workflow type (build time, runtime, or development), file format, and any context you provide. Google Slides also has a separate **Layout Processing** charge for each completed slide. -Review consumption under **Organization > Usage**. Select **Tokens**, **Agent**, or **Cost** if you can view billing. The page opens to the current billing period when one is available, or the last 30 days otherwise. You can also select the last 7 days or a custom date range of up to 100 days. +Review consumption under **Organization > Usage**. Switch between **Tokens** and **Agent**. If your role can view billing, **Cost** is also available. The page opens to the current billing period when one is available, or the last 30 days otherwise. You can also select the last 7 days or a custom date range of up to 100 days. - **Tokens** shows total and daily input tokens with breakdowns by target locale and service type. - **Agent** shows total and daily Organization-wide LCU usage. diff --git a/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx b/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx index d3a019f03..9144fa5e4 100644 --- a/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx +++ b/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx @@ -64,6 +64,8 @@ Click **History** to inspect translations from previous source versions. Use it - Restore a prior state - Confirm when a translated file changed +History loads in pages for files with many versions. Search by tag, message, or version ID, then press `Enter` or leave the search field to apply it across the full history. Click **Load more** to fetch older results. + You can also: - **Download** translated output diff --git a/docs/en-US/platform/dashboard/reference/api-keys.mdx b/docs/en-US/platform/dashboard/reference/api-keys.mdx index 70205bb52..e1263bb0f 100644 --- a/docs/en-US/platform/dashboard/reference/api-keys.mdx +++ b/docs/en-US/platform/dashboard/reference/api-keys.mdx @@ -29,9 +29,9 @@ Permissions are configured per resource. `Write` includes `Read`. | **Context** | Read Project and Organization context | Manage context groups, glossary, and directives | | **Runtime translation** | Not applicable | Translate content on demand | | **Translation queue** | Not applicable | Queue file translation jobs for background processing | -| **Project settings** | Not applicable | Update Project settings such as the default locale | +| **Project settings** | Not applicable | Update Project settings such as the default locale and CDN delivery | -Enable **Project creation** for automation that calls the [Create a Project](/docs/platform/openapi/reference/project/create-project) endpoint. Grant each key only the permissions it needs. +Enable **Project creation** for automation that calls the [Create a Project](/docs/platform/openapi/reference/project/create-project) endpoint. Also enable **Project settings** when that automation creates Projects with CDN delivery enabled. Grant each key only the permissions it needs. ## Create Project keys [#create-project-keys] diff --git a/docs/en-US/platform/dashboard/reference/organization-settings.mdx b/docs/en-US/platform/dashboard/reference/organization-settings.mdx index 5b3ea8c64..ac99a902e 100644 --- a/docs/en-US/platform/dashboard/reference/organization-settings.mdx +++ b/docs/en-US/platform/dashboard/reference/organization-settings.mdx @@ -31,7 +31,7 @@ For a detailed breakdown, see [roles and permissions](/docs/platform/dashboard/r ## Usage and billing [#usage-billing] -Open **Organization > Usage** to switch among **Tokens**, **Agent**, and **Cost** if your role can view billing. The page opens to the current billing period when one is available, or the last 30 days otherwise. You can also select the last 7 days or a custom range of up to 100 days. +Open **Organization > Usage** to switch between **Tokens** and **Agent**. If your role can view billing, **Cost** is also available. The page opens to the current billing period when one is available, or the last 30 days otherwise. You can also select the last 7 days or a custom range of up to 100 days. - **Tokens** shows total and daily input-token usage with target-locale and service-type breakdowns. - **Agent** shows total and daily Organization-wide LCU usage. @@ -39,7 +39,7 @@ Open **Organization > Usage** to switch among **Tokens**, **Agent**, and **Cost* The page also lists recent translation records with input and output token counts and recent Agent workflow records with trace IDs. When the Organization has multiple Projects, the Project selector filters token metrics and translation records; Agent and Cost totals remain Organization-wide. -Manage an Organization-owned plan, credit balance, and invoices from **Organization > Billing**. Expand an invoice to review its line items and quantities. Enterprise-managed Organizations use **Enterprise > Billing** instead. [Contact us](https://generaltranslation.com/en-US/enterprise/contact) if you're interested in Enterprise plans for larger teams with complex localization needs. +Manage an Organization-owned plan, credit balance, and invoices from **Organization > Billing**. Choose **Breakdown** on an invoice to review its line items and quantities. Enterprise-managed Organizations use **Enterprise > Billing** instead. [Contact us](https://generaltranslation.com/en-US/enterprise/contact) if you're interested in Enterprise plans for larger teams with complex localization needs. ## Connections [#connections] diff --git a/docs/en-US/platform/openapi/openapi.yaml b/docs/en-US/platform/openapi/openapi.yaml index 3445d4089..8697bbc5b 100644 --- a/docs/en-US/platform/openapi/openapi.yaml +++ b/docs/en-US/platform/openapi/openapi.yaml @@ -710,7 +710,8 @@ paths: description: > Create a project in the organization associated with an organization API key. The key must have the `org:projects:create` permission. Project keys - cannot use this endpoint. + cannot use this endpoint. Enabling CDN delivery also requires + `project:write`. operationId: createProject parameters: - $ref: '#/components/parameters/GtApiVersion' @@ -735,6 +736,10 @@ paths: type: string description: Source locale for the project. example: en-US + cdnEnabled: + type: boolean + default: false + description: Enable CDN delivery for the new project. responses: '201': description: Project created. @@ -762,7 +767,7 @@ paths: '403': description: > The API key lacks `org:projects:create` or is blocked by an access - policy. + policy, or `cdnEnabled` is true and the key lacks `project:write`. content: application/json: schema: @@ -816,7 +821,7 @@ paths: post: tags: [Project] summary: Update project information - description: Update project settings such as the default locale. + description: Update the project's default locale or CDN delivery setting. operationId: updateProjectInfo parameters: - $ref: '#/components/parameters/GtApiVersion' @@ -834,6 +839,9 @@ paths: type: object properties: defaultLocale: { type: string } + cdnEnabled: + type: boolean + description: Enable or disable CDN delivery. responses: '200': description: Project updated. diff --git a/docs/en-US/platform/openapi/overview.mdx b/docs/en-US/platform/openapi/overview.mdx index 3ef7bfce4..f9cefb916 100644 --- a/docs/en-US/platform/openapi/overview.mdx +++ b/docs/en-US/platform/openapi/overview.mdx @@ -58,7 +58,7 @@ Common permissions: - `project:translations:generate` for runtime translation. - `project:context:read` for reading context generation status. - `project:context:write` for generating context. -- `project:write` for updating Project settings. +- `project:write` for updating Project settings and enabling CDN delivery during Project creation. diff --git a/docs/en-US/platform/openapi/reference/project/create-project.mdx b/docs/en-US/platform/openapi/reference/project/create-project.mdx index 611548505..716c45b5e 100644 --- a/docs/en-US/platform/openapi/reference/project/create-project.mdx +++ b/docs/en-US/platform/openapi/reference/project/create-project.mdx @@ -15,7 +15,7 @@ Creates a Project in the Organization associated with an Organization API key. R POST https://api2.gtx.dev/v2/projects ``` -**Permission** `org:projects:create` · **Rate limit** Default (200/min) +**Permission** `org:projects:create`; `project:write` to enable CDN delivery · **Rate limit** Default (200/min) Use this endpoint to provision Projects from your own automation. Project API keys cannot create other Projects. @@ -24,6 +24,7 @@ Use this endpoint to provision Projects from your own automation. Project API ke - Authentication requires an [Organization API key](/docs/platform/dashboard/reference/api-keys#create-organization-keys) (`gtx-org-`) with `org:projects:create` permission. - The Organization is derived from the API key. Do not send an Organization or Project ID in the request. - The Project name is trimmed and validated. The default locale is validated and normalized, such as `en-us` to `en-US`. +- Set `cdnEnabled` to `true` to enable CDN delivery when the Project is created. This requires the key's `project:write` permission. Omitting the field leaves CDN delivery disabled. - The new Project copies the Organization's AI provider settings. Its locale allowlist copies the Organization allowlist except for locales in the same dialect as the default locale; it starts empty when the Organization has no allowlist. - Existing Organization members are linked to the new Project. - The request returns `409` without creating a Project when the Organization has reached its Project limit. @@ -34,7 +35,7 @@ Use this endpoint to provision Projects from your own automation. Project API ke | Header | Description | Required | | --- | --- | --- | -| `x-gt-api-key` | Organization API key with `org:projects:create`. | Yes | +| `x-gt-api-key` | Organization API key with `org:projects:create`, plus `project:write` when enabling CDN delivery. | Yes | | `gt-api-version` | API version. | No | Do not send `x-gt-project-id`. This endpoint derives the Organization from the API key and creates a new Project within it. @@ -47,6 +48,7 @@ Do not send `x-gt-project-id`. This endpoint derives the Organization from the A | --- | --- | --- | --- | --- | | `name` | Project name (1–64 characters). Supports letters, numbers, spaces, dashes, underscores, apostrophes, parentheses, and periods. | `string` | No | — | | `defaultLocale` | Source locale for the Project. | `string` | No | — | +| `cdnEnabled` | Whether to enable CDN delivery for the new Project. | `boolean` | Yes | `false` | Unknown fields are rejected. @@ -78,7 +80,7 @@ Unknown fields are rejected. | --- | --- | | `400` | Invalid API version, request body, Project name, or default locale. | | `401` | Missing, invalid, or non-Organization API key. | -| `403` | The key lacks `org:projects:create` or is blocked by an access policy. | +| `403` | The key lacks `org:projects:create`, lacks `project:write` when `cdnEnabled` is `true`, or is blocked by an access policy. | | `409` | The Organization has reached its Project limit. | | `429` | Rate limit exceeded. | | `500` | The Project could not be created. | @@ -92,6 +94,7 @@ curl -X POST https://api2.gtx.dev/v2/projects \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Portal", - "defaultLocale": "en-US" + "defaultLocale": "en-US", + "cdnEnabled": true }' ``` diff --git a/docs/en-US/platform/openapi/reference/project/update-project.mdx b/docs/en-US/platform/openapi/reference/project/update-project.mdx index 7c6a6628f..468ddd55b 100644 --- a/docs/en-US/platform/openapi/reference/project/update-project.mdx +++ b/docs/en-US/platform/openapi/reference/project/update-project.mdx @@ -6,7 +6,7 @@ description: Update General Translation Project-level settings from automation. method: POST --- -Updates Project-level settings such as the default locale. The Project ID in the path must match the authenticated Project. +Updates the Project's default locale or CDN delivery setting. The Project ID in the path must match the authenticated Project. ## Overview [#overview] @@ -22,6 +22,8 @@ Change a Project's settings from your own automation. To read the current settin - The `projectId` in the path must match the Project the API key is authenticated for. A missing or mismatched ID returns `400`. - When `defaultLocale` is provided, it is validated and set as the Project's default locale. Omitting it leaves the default locale unchanged. +- Set `cdnEnabled` to `true` to enable CDN delivery or `false` to disable it. Omitting it leaves the setting unchanged. +- You may send either field or both. An empty object succeeds without changing the Project. - The response confirms success. ## Request [#request] @@ -46,6 +48,7 @@ Change a Project's settings from your own automation. To read the current settin | Field | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | | `defaultLocale` | New default locale for the Project. | `string` | Yes | Unchanged | +| `cdnEnabled` | Whether CDN delivery is enabled for the Project. | `boolean` | Yes | Unchanged | ## Response [#response] @@ -61,7 +64,7 @@ Change a Project's settings from your own automation. To read the current settin | Status | Cause | | --- | --- | -| `400` | Missing or mismatched `projectId`, or an invalid `defaultLocale`. | +| `400` | Missing or mismatched `projectId`, invalid `defaultLocale`, or non-boolean `cdnEnabled`. | | `401` | Missing or invalid API key. | | `403` | API key lacks `project:write`. | | `429` | Rate limit exceeded. | @@ -73,6 +76,7 @@ curl -X POST https://api2.gtx.dev/v2/project/info/prj_... \ -H "x-gt-api-key: gtx-api-..." \ -H "Content-Type: application/json" \ -d '{ - "defaultLocale": "en" + "defaultLocale": "en", + "cdnEnabled": true }' ``` diff --git a/docs/en-US/react/(frameworks)/tanstack-start/index.mdx b/docs/en-US/react/(frameworks)/tanstack-start/index.mdx index e10614246..72b2dc536 100644 --- a/docs/en-US/react/(frameworks)/tanstack-start/index.mdx +++ b/docs/en-US/react/(frameworks)/tanstack-start/index.mdx @@ -15,7 +15,7 @@ If you are just getting started, follow the [TanStack Start Quickstart](/docs/re ## What is TanStack Start-specific [#overview] -- **Request middleware.** Register [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) from the `gt-tanstack-start/server` compatibility path in 11.1.4 to create request-local state for server functions. +- **Request middleware.** Register [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) from `gt-tanstack-start` to create request-local state for server functions. - **Router and root-route setup.** Call [`initializeGT`](/docs/react/reference/config#initialize) at module scope in `src/router.tsx`, resolve the locale with [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale), load a translations snapshot in the root route loader, and pass both to [``](/docs/react/reference/components/gt-provider). See [Setup](/docs/react/tanstack-start/setup). - **Locale routing.** Configure TanStack Router to accept both unprefixed and locale-prefixed URLs with either optional `/{-$locale}` route segments or URL rewrites. Then set `localeRouting` to `true` to keep non-default locales in the pathname while leaving the default locale unprefixed. See [Setup](/docs/react/tanstack-start/setup#locale-routing). - **Isomorphic runtime functions.** Read runtime state and translate with [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale), [`getEnableI18n`](/docs/react/tanstack-start/reference/functions/get-enable-i18n), [`getGT`](/docs/react/tanstack-start/reference/functions/get-gt), [`getMessages`](/docs/react/tanstack-start/reference/functions/get-messages), and [`getTranslations`](/docs/react/tanstack-start/reference/functions/get-translations). On the server, call them inside the [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) request scope. diff --git a/docs/en-US/react/(frameworks)/tanstack-start/reference/functions/gt-middleware.mdx b/docs/en-US/react/(frameworks)/tanstack-start/reference/functions/gt-middleware.mdx index 0bbc4fb3f..9563de2de 100644 --- a/docs/en-US/react/(frameworks)/tanstack-start/reference/functions/gt-middleware.mdx +++ b/docs/en-US/react/(frameworks)/tanstack-start/reference/functions/gt-middleware.mdx @@ -5,13 +5,13 @@ description: Create request-scoped locale state for General Translation server A --- -The `gtMiddleware` export is global TanStack Start request middleware. Import it from `gt-tanstack-start/server` and register it before calling runtime helpers on the server. +The `gtMiddleware` export is global TanStack Start request middleware. Import it from `gt-tanstack-start` and register it before calling runtime helpers on the server. ## Overview [#overview] ```ts title="src/start.ts" import { createCsrfMiddleware, createStart } from '@tanstack/react-start'; -import { gtMiddleware } from 'gt-tanstack-start/server'; +import { gtMiddleware } from 'gt-tanstack-start'; const csrfMiddleware = createCsrfMiddleware({ filter: ({ handlerType }) => handlerType === 'serverFn', @@ -22,10 +22,6 @@ export const startInstance = createStart(() => ({ })); ``` - - **`gt-tanstack-start` 11.1.4:** The package marks the `/server` path as deprecated, but its root browser build does not export `gtMiddleware`. Use the compatibility import above for this release. - - ## How it works [#how-it-works] - Resolves the locale, region, and internationalization setting from the incoming request and your General Translation configuration. @@ -48,3 +44,9 @@ The middleware provides request state to: - [`getTranslations`](/docs/react/tanstack-start/reference/functions/get-translations) These helpers are isomorphic. Their server branches throw when called outside the active middleware request scope; their client branches read the browser condition store initialized by [`initializeGT`](/docs/react/reference/config#initialize). + +## Version history [#version-history] + +| Version | Changes | +| --- | --- | +| `11.1.5` | Exported `gtMiddleware` from the root browser condition so setup files can use the root import in client builds. | diff --git a/docs/en-US/react/(frameworks)/tanstack-start/setup.mdx b/docs/en-US/react/(frameworks)/tanstack-start/setup.mdx index 1ebf88124..28af40482 100644 --- a/docs/en-US/react/(frameworks)/tanstack-start/setup.mdx +++ b/docs/en-US/react/(frameworks)/tanstack-start/setup.mdx @@ -34,7 +34,7 @@ Create `src/start.ts` and register [`gtMiddleware`](/docs/react/tanstack-start/r ```ts title="src/start.ts" import { createCsrfMiddleware, createStart } from '@tanstack/react-start'; -import { gtMiddleware } from 'gt-tanstack-start/server'; +import { gtMiddleware } from 'gt-tanstack-start'; const csrfMiddleware = createCsrfMiddleware({ filter: ({ handlerType }) => handlerType === 'serverFn', @@ -45,8 +45,6 @@ export const startInstance = createStart(() => ({ })); ``` -The `/server` compatibility import is required for the browser export in `gt-tanstack-start` 11.1.4. See the [`gtMiddleware` reference](/docs/react/tanstack-start/reference/functions/gt-middleware) for version details. - The middleware resolves the locale, region, and internationalization setting once per request. It persists the resolved locale in the locale cookie and makes request state available to the [isomorphic runtime functions](/docs/react/tanstack-start/using-server-functions) on the server. ## Initialize and resolve the locale [#initialize] diff --git a/docs/en-US/react/guides/developing-spa-translations.mdx b/docs/en-US/react/guides/developing-spa-translations.mdx index 42506abe3..d6e076c17 100644 --- a/docs/en-US/react/guides/developing-spa-translations.mdx +++ b/docs/en-US/react/guides/developing-spa-translations.mdx @@ -203,7 +203,7 @@ See the complete [`gt-react` Vite example](https://github.com/generaltranslation ### 3. Add development credentials -Get a development API key at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or by running: +Get a development API key at [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) or by running: ```bash npx gt auth diff --git a/docs/en-US/react/nextjs-pages-router-quickstart.mdx b/docs/en-US/react/nextjs-pages-router-quickstart.mdx index 9a71b4fa9..0467b88eb 100644 --- a/docs/en-US/react/nextjs-pages-router-quickstart.mdx +++ b/docs/en-US/react/nextjs-pages-router-quickstart.mdx @@ -254,7 +254,7 @@ GT_API_KEY="your-api-key" GT_PROJECT_ID="your-project-id" ``` -Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or by running: +Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) or by running: ```bash npx gt auth diff --git a/docs/en-US/react/nextjs-quickstart.mdx b/docs/en-US/react/nextjs-quickstart.mdx index f412be8b0..5c2f3ec2f 100644 --- a/docs/en-US/react/nextjs-quickstart.mdx +++ b/docs/en-US/react/nextjs-quickstart.mdx @@ -212,7 +212,7 @@ GT_API_KEY="your-api-key" GT_PROJECT_ID="your-project-id" ``` -Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or by running: +Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) or by running: ```bash npx gt auth diff --git a/docs/en-US/react/overview.mdx b/docs/en-US/react/overview.mdx index 3dfd56fbd..86bdef132 100644 --- a/docs/en-US/react/overview.mdx +++ b/docs/en-US/react/overview.mdx @@ -1,33 +1,35 @@ --- title: Overview -description: Learn about General Translation React libraries and which quickstart to follow for your framework. +description: Learn which React library and quickstart fit your framework. --- -General Translation internationalization libraries for React apps share components, hooks, and configurations across React SPA, Next.js App Router, Next.js Pages Router, TanStack Start, and React Native. +General Translation's React internationalization libraries share components, hooks, and configuration across React SPAs, Next.js App Router, Next.js Pages Router, TanStack Start, and React Native. This is the landing page for the React section. Read on to understand the ecosystem and pick your framework, then follow the matching quickstart. ## The React ecosystem [#ecosystem] -Each framework has its own package: +Each framework family has its own package: - `gt-react` — for server-rendered React apps and single-page apps (SPAs), such as Vite or Create React App. See the [React Quickstart](/docs/react/react-quickstart) or [React SPA Quickstart](/docs/react/react-spa-quickstart). - `gt-next` — for Next.js App Router and Pages Router apps. See the [Next.js App Router Quickstart](/docs/react/nextjs-quickstart) or [Next.js Pages Router Quickstart](/docs/react/nextjs-pages-router-quickstart). - `gt-tanstack-start` — for TanStack Start apps. See the [TanStack Start Quickstart](/docs/react/tanstack-start-quickstart). - `gt-react-native` — for React Native apps, including Expo and the bare React Native CLI. See the [React Native Quickstart](/docs/react/react-native-quickstart). +*Note:* `gt-tanstack-start` and `gt-react-native` are experimental. Review their quickstarts for current limitations before choosing either one. + ## Shared translation model [#shared-model] -Because every React i18n library is built around the same core component and hooks, there's only one interface to learn. The important parts are: +Because every React i18n library shares the same core components and hooks, there is one translation model to learn. The important parts are: - [``](/docs/react/reference/components/t) **component.** Wrap any JSX in [``](/docs/react/reference/components/t) to translate it in place, including nested elements and formatting. [``](/docs/react/reference/components/t) translates its contents as a single unit. - [`useGT`](/docs/react/reference/hooks/use-gt) **hook.** Translate standalone strings — placeholders, `aria-label` values, alt text — with the function it returns. Call it as `const gt = useGT();`, then `gt('Hello, world!')`. In async App Router components, use [`getGT`](/docs/react/nextjs/reference/functions/get-gt) from `gt-next/server`. - [`GTProvider`](/docs/react/reference/components/gt-provider) **component.** Wrap your app so components can access translations and the active locale. How you supply translations to it differs slightly per framework, which is why each has its own quickstart. - `gt` **CLI.** The `gt` package generates and downloads translations. Its [`gt.config.json`](/docs/cli/reference/config) file declares your `defaultLocale`, target `locales`, and translation output paths. Run [`npx gt translate`](/docs/cli/reference/commands/translate) to translate your project through the General Translation API. -Variable components ([``](/docs/react/reference/components/var), [``](/docs/react/reference/components/num), [``](/docs/react/reference/components/currency), [``](/docs/react/reference/components/datetime)), the [``](/docs/react/reference/components/plural) and [``](/docs/react/reference/components/derive) components, and helper hooks are shared across all frameworks too. +Variable components ([``](/docs/react/reference/components/var), [``](/docs/react/reference/components/num), [``](/docs/react/reference/components/currency), and [``](/docs/react/reference/components/datetime)) are also shared, along with [``](/docs/react/reference/components/plural), [``](/docs/react/reference/components/branch), [``](/docs/react/reference/components/derive), and locale hooks such as [`useLocale`](/docs/react/reference/hooks/use-locale). ## Choose your framework [#frameworks] diff --git a/docs/en-US/react/react-quickstart.mdx b/docs/en-US/react/react-quickstart.mdx index 5d2a3a162..a8fa9556a 100644 --- a/docs/en-US/react/react-quickstart.mdx +++ b/docs/en-US/react/react-quickstart.mdx @@ -200,7 +200,7 @@ VITE_GT_DEV_API_KEY="your-dev-api-key" For other frameworks, use their client environment-variable convention and pass the exposed values to [`initializeGT`](/docs/react/reference/config#initialize). -Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or by running: +Get your free keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) or by running: ```bash npx gt auth diff --git a/docs/en-US/react/react-spa-quickstart.mdx b/docs/en-US/react/react-spa-quickstart.mdx index 10bbf7aee..240c68536 100644 --- a/docs/en-US/react/react-spa-quickstart.mdx +++ b/docs/en-US/react/react-spa-quickstart.mdx @@ -21,7 +21,7 @@ In a single-page app, `gt-react` runs entirely in the browser — you initialize - Node.js 18+ - **Tip:** Run `npx gt@latest` to configure everything with the [Setup Wizard](/docs/cli/quickstart). This guide covers manual setup. + **Tip:** Run `npx gt@latest` to configure the Vite bootstrap and translation loading with the [setup wizard](/docs/cli/quickstart). This guide covers manual setup. @@ -108,10 +108,6 @@ export default async function loadTranslations(locale: string) { This function loads JSON translation files from your `src/_gt/` directory. The CLI generates these files when you run [`npx gt translate`](/docs/cli/reference/commands/translate). - - **Note:** Rollup cannot analyze this fully dynamic import path. Use the [static locale-loader map](/docs/react/guides/developing-spa-translations#setup) shown in the SPA development guide. - - ### 4. Initialize the library diff --git a/docs/en-US/react/tanstack-start-quickstart.mdx b/docs/en-US/react/tanstack-start-quickstart.mdx index 2d7dc93b5..2009e9676 100644 --- a/docs/en-US/react/tanstack-start-quickstart.mdx +++ b/docs/en-US/react/tanstack-start-quickstart.mdx @@ -92,7 +92,7 @@ Create `src/start.ts` and register [`gtMiddleware`](/docs/react/tanstack-start/r ```ts title="src/start.ts" import { createCsrfMiddleware, createStart } from '@tanstack/react-start'; -import { gtMiddleware } from 'gt-tanstack-start/server'; +import { gtMiddleware } from 'gt-tanstack-start'; const csrfMiddleware = createCsrfMiddleware({ filter: ({ handlerType }) => handlerType === 'serverFn', @@ -103,8 +103,6 @@ export const startInstance = createStart(() => ({ })); ``` -The `/server` compatibility import keeps this setup working with the browser export in `gt-tanstack-start` 11.1.4. See the [`gtMiddleware` reference](/docs/react/tanstack-start/reference/functions/gt-middleware) for version details. - The middleware scopes the locale, region, and internationalization setting to each request so server functions use the correct language. Complete the initialization in the next step before starting the development server. ### 5. Initialize General Translation and set up the root route From a1aba2ff1277a303655b0a58e5b73b8bc0058765 Mon Sep 17 00:00:00 2001 From: taylor-fang Date: Wed, 5 Aug 2026 17:55:04 -0700 Subject: [PATCH 07/13] docs: improve React reference and search metadata (#440) Co-authored-by: Cursor Agent Co-authored-by: taylor-fang --- DOCS-SKILL.md | 5 +- docs/en-US/overview/meta.json | 1 + docs/en-US/platform/index.mdx | 4 +- .../nextjs/reference/components/tx.mdx | 4 +- .../react/reference/components/branch.mdx | 4 +- .../react/reference/components/currency.mdx | 4 +- .../react/reference/components/datetime.mdx | 4 +- .../react/reference/components/derive.mdx | 4 +- .../reference/components/gt-provider.mdx | 4 +- .../reference/components/locale-selector.mdx | 4 +- docs/en-US/react/reference/components/num.mdx | 4 +- .../react/reference/components/plural.mdx | 4 +- .../reference/components/region-selector.mdx | 4 +- .../reference/components/relative-time.mdx | 4 +- docs/en-US/react/reference/components/t.mdx | 4 +- docs/en-US/react/reference/components/var.mdx | 4 +- docs/en-US/react/reference/config.mdx | 2 +- .../react/reference/functions/declare-var.mdx | 2 +- .../react/reference/functions/decode-vars.mdx | 2 +- .../react/reference/functions/derive.mdx | 2 +- .../functions/get-translations-snapshot.mdx | 2 +- .../reference/functions/load-dictionary.mdx | 2 +- .../reference/functions/load-translations.mdx | 2 +- docs/en-US/react/reference/functions/msg.mdx | 2 +- .../react/reference/functions/t-function.mdx | 2 +- .../reference/hooks/use-default-locale.mdx | 2 +- docs/en-US/react/reference/hooks/use-gt.mdx | 2 +- .../reference/hooks/use-locale-direction.mdx | 2 +- .../reference/hooks/use-locale-properties.mdx | 2 +- .../reference/hooks/use-locale-selector.mdx | 2 +- .../react/reference/hooks/use-locale.mdx | 2 +- .../react/reference/hooks/use-locales.mdx | 2 +- .../react/reference/hooks/use-messages.mdx | 2 +- .../reference/hooks/use-region-selector.mdx | 2 +- .../react/reference/hooks/use-region.mdx | 2 +- .../react/reference/hooks/use-set-locale.mdx | 2 +- .../react/reference/hooks/use-set-region.mdx | 2 +- .../reference/hooks/use-translations.mdx | 2 +- docs/en-US/react/reference/lint-rules.mdx | 2 +- .../types/dictionary-translation-options.mdx | 2 +- .../types/inline-translation-options.mdx | 2 +- scripts/test-validate-docs-structure.ts | 58 +++++++++++ scripts/validate-docs-structure.ts | 98 ++++++++++++++++++- 43 files changed, 213 insertions(+), 55 deletions(-) diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md index 4aa8f05d7..018c1d330 100644 --- a/DOCS-SKILL.md +++ b/DOCS-SKILL.md @@ -166,6 +166,7 @@ Use a bolded breadcrumb with `>`: **Project > Automations**, **Project > Context - Always write **General Translation** (singular) — never "General Translations". The API is the **General Translation API**, not "General Translations API". - Use **General Translation** when the page needs to identify the overall product, distinguish it from another service, or name an official term such as the **General Translation API**. Do not force the name into every page or `description`; the section title, sidebar, package name, or feature name often supplies enough context. +- **Do not repeat the product or package name when the surrounding section already establishes it.** In page descriptions and opening sentences, omit **General Translation**, `gt-react`, `gt-next`, and similar ownership labels when the section, page title, sidebar, or reference grouping already supplies that context. Start with the reader action or API behavior instead. - Do not prefix every product-owned feature with the brand. Prefer **the CLI**, **the Dashboard**, **the integration**, **Ask AI**, **Context Groups**, or the package name over "the General Translation CLI/tool/integration/Ask AI" once the subject is clear. - Remove redundant branding, not meaning. Keep ordinary words such as "translation," "translations," "translate," and "translation workflow" when they explain what the reader is doing. - Configuration pages should name the thing being configured. Keep **General Translation**, `gt`, or the relevant package name when it distinguishes the configuration from the third-party platform's own settings. @@ -289,7 +290,7 @@ Every immediate child folder listed by a top-level section root becomes a visibl ### Overview hub -The **overview** section doubles as a **landing hub**: its `meta.json` lists the overview pages (introduction, key concepts, for coding agents) directly, then uses separators (`---Frameworks---`, `---Platform---`) with **cross-section link entries** to surface the main frameworks and Platform capabilities without duplicating their content. Keep those curated links in sync with the sections they point to, and only link pages that exist. +The **overview** section doubles as a **landing hub**: its `meta.json` lists the overview pages (introduction, key concepts, for coding agents) directly, then uses separators (`---Frameworks---`, `---Platform---`) with **cross-section link entries** to surface the main frameworks and Platform capabilities without duplicating their content. Include every published Platform capability and integration section, keep those links in sync with the sections they point to, and only link pages that exist. The structure validator enforces this coverage. ### Machine-readable outputs @@ -426,12 +427,14 @@ description: How to use labels, notes, and comments to coordinate translation re - **Frontmatter is YAML, not plain prose.** Parse every touched page after bulk frontmatter edits. Quote or rewrite scalar values containing YAML-significant punctuation, especially a colon followed by a space (`: `), a leading special character, or an inline `#`; visual inspection and a successful Markdown render are not sufficient. - `title`: **sentence case** — capitalize only the first word, except proper/product names (Dashboard, Locadex, Core, Organization, Project, Enterprise, Context Group, Glossary, Directives, GitHub). No trailing spaces. The docs layout renders this value as the page H1, so do not repeat it as a `#` heading in the body. +- **React component reference titles use JSX syntax.** Quote the complete tag in frontmatter (`title: ""`) so the page title and sidebar display ``, not `T`. - `description`: no backticks, and **end with a period** (a question ends with `?` instead) — the description is used verbatim as the HTML meta description and in machine-readable indexes (`llms.txt`), where backticks render as literal characters. Refer to a component by its angle-bracket tag with no backticks (``, ``), not the bare word; where the same description appears in a `` body, escape the tag as `` so the MDX still parses. Name the relevant capability directly; do not add **General Translation** when the section, title, or feature name already makes ownership clear. If the product name is genuinely needed, spell out **General Translation**, never GT. Phrasing depends on page type: - **Guides** lead with **"How to…"** for SEO. Write **one concise sentence** that states what the reader will accomplish and names the relevant capability or tool without automatically branding it. Add enough scope to distinguish the description from the title, but **do not** restate the title, enumerate every subsection, or append a `: this guide covers …` checklist. For a guide that explains a concept rather than a task, use a question instead. *Examples:* "How to upload, translate, and download files with the generaltranslation library." / "How to review translations, make manual edits, and compare locales in the Dashboard." / "What are locale codes, and how are they used across the translation stack?" - **Configuration Guides:** retain `gt`, the package name, or **General Translation** when it identifies which system's configuration the reader is changing. *Example:* "How to configure the General Translation gt-sanity plugin for locales, document filters, and credentials." - **Other pages** (Quickstart, Get Started, hubs) use one action-oriented sentence ending with a period ("Configure…", "Review…", "Learn…"). - **Reference pages** add a second sentence naming what the page documents. Choose the lead by page type: - **API/library reference** (a function, method, type, command, or endpoint) uses `API reference for [function/method/type]` — including OpenAPI endpoints. *Example: "…into a target locale. API reference for translateField."* + - **React components:** name the JSX tag directly (`API reference for the component.`). - **Non-API reference** (a settings page, config area, file format, or other non-API surface) uses `Reference for [topic]` — do not start the sentence with "API reference". *Example: "…across every locale. Reference for supported file formats."* A few optional fields appear on specific page types: diff --git a/docs/en-US/overview/meta.json b/docs/en-US/overview/meta.json index 92e7854db..8f0fc6fa0 100644 --- a/docs/en-US/overview/meta.json +++ b/docs/en-US/overview/meta.json @@ -16,6 +16,7 @@ "[Mintlify](/docs/integrations/mintlify/quickstart)", "[Sanity](/docs/integrations/sanity/quickstart)", "[Storyblok](/docs/integrations/storyblok/quickstart)", + "[Google Drive](/docs/integrations/google-drive/quickstart)", "[Markdown](/docs/cli/reference/formats/mdx-md-files)", "[JSON](/docs/cli/reference/formats/json-files)", "---Platform---", diff --git a/docs/en-US/platform/index.mdx b/docs/en-US/platform/index.mdx index 6d6cba909..bfaad64c7 100644 --- 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 --- -These sections cover the Dashboard, the core `generaltranslation` library, Locadex, and the HTTP API. +These sections cover the Dashboard, the `generaltranslation` Core library, Locadex, and the HTTP API. @@ -15,7 +15,7 @@ These sections cover the Dashboard, the core `generaltranslation` library, Locad Learn how to use Locadex, the AI agent which connects your codebase, translations, and content sources. - Learn what the `generaltranslation` core library does, when to use it, and how to translate your first string. + Learn what the Core library does, when to use it, and how to translate your first string. Learn how to use the public General Translation API endpoints and the OpenAPI spec. diff --git a/docs/en-US/react/(frameworks)/nextjs/reference/components/tx.mdx b/docs/en-US/react/(frameworks)/nextjs/reference/components/tx.mdx index ded219e03..0bf810ade 100644 --- a/docs/en-US/react/(frameworks)/nextjs/reference/components/tx.mdx +++ b/docs/en-US/react/(frameworks)/nextjs/reference/components/tx.mdx @@ -1,7 +1,7 @@ --- -title: Tx -description: Translate request-time JSX in Next.js App Router server components with General Translation. API reference for Tx. +title: "" +description: Translate request-time JSX in Next.js App Router server components. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/branch.mdx b/docs/en-US/react/reference/components/branch.mdx index 8c09c170a..bfe552521 100644 --- a/docs/en-US/react/reference/components/branch.mdx +++ b/docs/en-US/react/reference/components/branch.mdx @@ -1,7 +1,7 @@ --- -title: Branch -description: Render content conditionally based on a value with General Translation gt-react. API reference for Branch. +title: "" +description: Render content conditionally based on a value. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/currency.mdx b/docs/en-US/react/reference/components/currency.mdx index 0e0ade9ee..cdb01058c 100644 --- a/docs/en-US/react/reference/components/currency.mdx +++ b/docs/en-US/react/reference/components/currency.mdx @@ -1,7 +1,7 @@ --- -title: Currency -description: Format a currency amount for the active locale with General Translation gt-react. API reference for Currency. +title: "" +description: Format a currency amount for the active locale. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/datetime.mdx b/docs/en-US/react/reference/components/datetime.mdx index 114a5b2e0..9c4dbdc55 100644 --- a/docs/en-US/react/reference/components/datetime.mdx +++ b/docs/en-US/react/reference/components/datetime.mdx @@ -1,7 +1,7 @@ --- -title: DateTime -description: Format a date and time for the active locale with General Translation gt-react. API reference for DateTime. +title: "" +description: Format a date and time for the active locale. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/derive.mdx b/docs/en-US/react/reference/components/derive.mdx index 5bb3f9d10..1e4532459 100644 --- a/docs/en-US/react/reference/components/derive.mdx +++ b/docs/en-US/react/reference/components/derive.mdx @@ -1,7 +1,7 @@ --- -title: Derive -description: Mark finite content variants for extraction inside a translation with General Translation gt-react. API reference for Derive. +title: "" +description: Mark finite content variants for extraction inside a translation. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/gt-provider.mdx b/docs/en-US/react/reference/components/gt-provider.mdx index 707e5866a..cb85c9fae 100644 --- a/docs/en-US/react/reference/components/gt-provider.mdx +++ b/docs/en-US/react/reference/components/gt-provider.mdx @@ -1,7 +1,7 @@ --- -title: GTProvider -description: Provide the active locale and translations to a General Translation gt-react component tree. API reference for GTProvider. +title: "" +description: Provide the active locale and translations to the component tree. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/locale-selector.mdx b/docs/en-US/react/reference/components/locale-selector.mdx index 872d051fd..65863ab4f 100644 --- a/docs/en-US/react/reference/components/locale-selector.mdx +++ b/docs/en-US/react/reference/components/locale-selector.mdx @@ -1,7 +1,7 @@ --- -title: LocaleSelector -description: Render a dropdown for switching the active locale with General Translation gt-react. API reference for LocaleSelector. +title: "" +description: Render a dropdown for switching the active locale. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/num.mdx b/docs/en-US/react/reference/components/num.mdx index 785cca170..1bf1fa0ee 100644 --- a/docs/en-US/react/reference/components/num.mdx +++ b/docs/en-US/react/reference/components/num.mdx @@ -1,7 +1,7 @@ --- -title: Num -description: Format a number for the active locale with General Translation gt-react. API reference for Num. +title: "" +description: Format a number for the active locale. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/plural.mdx b/docs/en-US/react/reference/components/plural.mdx index e837001b4..d802a39c4 100644 --- a/docs/en-US/react/reference/components/plural.mdx +++ b/docs/en-US/react/reference/components/plural.mdx @@ -1,7 +1,7 @@ --- -title: Plural -description: Render count-based content using the active locale's plural rules with General Translation gt-react. API reference for Plural. +title: "" +description: Render count-based content using the active locale's plural rules. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/region-selector.mdx b/docs/en-US/react/reference/components/region-selector.mdx index ec1e5a29f..f051d0382 100644 --- a/docs/en-US/react/reference/components/region-selector.mdx +++ b/docs/en-US/react/reference/components/region-selector.mdx @@ -1,7 +1,7 @@ --- -title: RegionSelector -description: Render a dropdown for switching the active region with General Translation gt-react. API reference for RegionSelector. +title: "" +description: Render a dropdown for switching the active region. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/relative-time.mdx b/docs/en-US/react/reference/components/relative-time.mdx index 268397711..1f87223fc 100644 --- a/docs/en-US/react/reference/components/relative-time.mdx +++ b/docs/en-US/react/reference/components/relative-time.mdx @@ -1,7 +1,7 @@ --- -title: RelativeTime -description: Format a localized relative time such as "2 hours ago" with General Translation gt-react. API reference for RelativeTime. +title: "" +description: Format localized relative time, such as 2 hours ago. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/t.mdx b/docs/en-US/react/reference/components/t.mdx index dbb598666..4cd4b22af 100644 --- a/docs/en-US/react/reference/components/t.mdx +++ b/docs/en-US/react/reference/components/t.mdx @@ -1,7 +1,7 @@ --- -title: T -description: Translate JSX children in place with General Translation gt-react. API reference for T. +title: "" +description: Translate JSX children in place. API reference for the component. --- diff --git a/docs/en-US/react/reference/components/var.mdx b/docs/en-US/react/reference/components/var.mdx index 3c81be250..9241820e4 100644 --- a/docs/en-US/react/reference/components/var.mdx +++ b/docs/en-US/react/reference/components/var.mdx @@ -1,7 +1,7 @@ --- -title: Var -description: Render a dynamic value inside a translation without translating it, with General Translation gt-react. API reference for Var. +title: "" +description: Render a dynamic value inside a translation without translating it. API reference for the component. --- diff --git a/docs/en-US/react/reference/config.mdx b/docs/en-US/react/reference/config.mdx index 40d747fa4..9fd6813a9 100644 --- a/docs/en-US/react/reference/config.mdx +++ b/docs/en-US/react/reference/config.mdx @@ -1,7 +1,7 @@ --- title: Configuration -description: Configure General Translation across the React ecosystem with the shared gt.config.json file and runtime initialization. API reference for gt.config.json. +description: Configure the React ecosystem with the shared gt.config.json file and runtime initialization. Reference for gt.config.json. --- diff --git a/docs/en-US/react/reference/functions/declare-var.mdx b/docs/en-US/react/reference/functions/declare-var.mdx index 91c4748f4..d0c747ed7 100644 --- a/docs/en-US/react/reference/functions/declare-var.mdx +++ b/docs/en-US/react/reference/functions/declare-var.mdx @@ -1,7 +1,7 @@ --- title: declareVar -description: Mark a non-translatable variable inside derived content with General Translation gt-react. API reference for declareVar. +description: Mark a non-translatable variable inside derived content. API reference for declareVar. --- diff --git a/docs/en-US/react/reference/functions/decode-vars.mdx b/docs/en-US/react/reference/functions/decode-vars.mdx index 7e99fd80f..c89e43ec8 100644 --- a/docs/en-US/react/reference/functions/decode-vars.mdx +++ b/docs/en-US/react/reference/functions/decode-vars.mdx @@ -1,7 +1,7 @@ --- title: decodeVars -description: Expand variables encoded by declareVar back into their values with General Translation gt-react. API reference for decodeVars. +description: Expand variables encoded by declareVar back into their values. API reference for decodeVars. --- diff --git a/docs/en-US/react/reference/functions/derive.mdx b/docs/en-US/react/reference/functions/derive.mdx index 9c4cb27fa..d56f9b3fa 100644 --- a/docs/en-US/react/reference/functions/derive.mdx +++ b/docs/en-US/react/reference/functions/derive.mdx @@ -1,7 +1,7 @@ --- title: derive -description: Mark finite content variants inside a string translation for extraction with General Translation gt-react. API reference for derive. +description: Mark finite content variants inside a string translation for extraction. API reference for derive. --- diff --git a/docs/en-US/react/reference/functions/get-translations-snapshot.mdx b/docs/en-US/react/reference/functions/get-translations-snapshot.mdx index 8ead863ae..2deac7c3a 100644 --- a/docs/en-US/react/reference/functions/get-translations-snapshot.mdx +++ b/docs/en-US/react/reference/functions/get-translations-snapshot.mdx @@ -1,7 +1,7 @@ --- title: getTranslationsSnapshot -description: Load a locale's translations for the General Translation gt-react provider. API reference for getTranslationsSnapshot. +description: Load a locale's translations for GTProvider. API reference for getTranslationsSnapshot. --- diff --git a/docs/en-US/react/reference/functions/load-dictionary.mdx b/docs/en-US/react/reference/functions/load-dictionary.mdx index ac0969ff3..ae62291e8 100644 --- a/docs/en-US/react/reference/functions/load-dictionary.mdx +++ b/docs/en-US/react/reference/functions/load-dictionary.mdx @@ -1,7 +1,7 @@ --- title: loadDictionary -description: Load your own dictionary translations as a standalone i18n library with General Translation gt-react. API reference for loadDictionary. +description: Load your own dictionary translations as a standalone i18n library. API reference for loadDictionary. --- diff --git a/docs/en-US/react/reference/functions/load-translations.mdx b/docs/en-US/react/reference/functions/load-translations.mdx index 4669afb64..bbedb06d3 100644 --- a/docs/en-US/react/reference/functions/load-translations.mdx +++ b/docs/en-US/react/reference/functions/load-translations.mdx @@ -1,7 +1,7 @@ --- title: loadTranslations -description: Customize how translations are loaded in production with General Translation gt-react. API reference for loadTranslations. +description: Customize how translations are loaded in production. API reference for loadTranslations. --- diff --git a/docs/en-US/react/reference/functions/msg.mdx b/docs/en-US/react/reference/functions/msg.mdx index a9255a81a..ca5baca6f 100644 --- a/docs/en-US/react/reference/functions/msg.mdx +++ b/docs/en-US/react/reference/functions/msg.mdx @@ -1,7 +1,7 @@ --- title: msg -description: Register and encode a string for translation at module scope with General Translation gt-react. API reference for msg. +description: Register and encode a string for translation at module scope. API reference for msg. --- diff --git a/docs/en-US/react/reference/functions/t-function.mdx b/docs/en-US/react/reference/functions/t-function.mdx index da5d9e237..49dbf10c1 100644 --- a/docs/en-US/react/reference/functions/t-function.mdx +++ b/docs/en-US/react/reference/functions/t-function.mdx @@ -1,7 +1,7 @@ --- title: t -description: Translate strings synchronously at module scope with General Translation gt-react. API reference for t. +description: Translate strings synchronously at module scope. API reference for t. --- diff --git a/docs/en-US/react/reference/hooks/use-default-locale.mdx b/docs/en-US/react/reference/hooks/use-default-locale.mdx index 24b32fd93..b5d5be5ac 100644 --- a/docs/en-US/react/reference/hooks/use-default-locale.mdx +++ b/docs/en-US/react/reference/hooks/use-default-locale.mdx @@ -1,7 +1,7 @@ --- title: useDefaultLocale -description: Read the source (default) locale with General Translation gt-react. API reference for useDefaultLocale. +description: Read the source (default) locale. API reference for useDefaultLocale. --- diff --git a/docs/en-US/react/reference/hooks/use-gt.mdx b/docs/en-US/react/reference/hooks/use-gt.mdx index 6ee214719..5518b3364 100644 --- a/docs/en-US/react/reference/hooks/use-gt.mdx +++ b/docs/en-US/react/reference/hooks/use-gt.mdx @@ -1,7 +1,7 @@ --- title: useGT -description: Get a function to translate strings inline with General Translation gt-react. API reference for useGT. +description: Get a function to translate strings inline. API reference for useGT. --- diff --git a/docs/en-US/react/reference/hooks/use-locale-direction.mdx b/docs/en-US/react/reference/hooks/use-locale-direction.mdx index 2a7dd8ad2..f96843a41 100644 --- a/docs/en-US/react/reference/hooks/use-locale-direction.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-direction.mdx @@ -1,7 +1,7 @@ --- title: useLocaleDirection -description: Read the text direction for a locale with General Translation gt-react. API reference for useLocaleDirection. +description: Read the text direction for a locale. API reference for useLocaleDirection. --- diff --git a/docs/en-US/react/reference/hooks/use-locale-properties.mdx b/docs/en-US/react/reference/hooks/use-locale-properties.mdx index 742abb52a..565cbb44b 100644 --- a/docs/en-US/react/reference/hooks/use-locale-properties.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-properties.mdx @@ -1,7 +1,7 @@ --- title: useLocaleProperties -description: Read display metadata for a locale with General Translation gt-react. API reference for useLocaleProperties. +description: Read display metadata for a locale. API reference for useLocaleProperties. --- diff --git a/docs/en-US/react/reference/hooks/use-locale-selector.mdx b/docs/en-US/react/reference/hooks/use-locale-selector.mdx index 885dfab08..df30ef794 100644 --- a/docs/en-US/react/reference/hooks/use-locale-selector.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-selector.mdx @@ -1,7 +1,7 @@ --- title: useLocaleSelector -description: Build a custom locale switcher with General Translation gt-react. API reference for useLocaleSelector. +description: Build a custom locale switcher. API reference for useLocaleSelector. --- diff --git a/docs/en-US/react/reference/hooks/use-locale.mdx b/docs/en-US/react/reference/hooks/use-locale.mdx index 7d2a3ab7a..249bb3863 100644 --- a/docs/en-US/react/reference/hooks/use-locale.mdx +++ b/docs/en-US/react/reference/hooks/use-locale.mdx @@ -1,7 +1,7 @@ --- title: useLocale -description: Read the active locale with General Translation gt-react. API reference for useLocale. +description: Read the active locale. API reference for useLocale. --- diff --git a/docs/en-US/react/reference/hooks/use-locales.mdx b/docs/en-US/react/reference/hooks/use-locales.mdx index 686ce0ee7..f6069177a 100644 --- a/docs/en-US/react/reference/hooks/use-locales.mdx +++ b/docs/en-US/react/reference/hooks/use-locales.mdx @@ -1,7 +1,7 @@ --- title: useLocales -description: List the supported locales with General Translation gt-react. API reference for useLocales. +description: List the supported locales. API reference for useLocales. --- diff --git a/docs/en-US/react/reference/hooks/use-messages.mdx b/docs/en-US/react/reference/hooks/use-messages.mdx index f1a2d4dcc..29d8fcce0 100644 --- a/docs/en-US/react/reference/hooks/use-messages.mdx +++ b/docs/en-US/react/reference/hooks/use-messages.mdx @@ -1,7 +1,7 @@ --- title: useMessages -description: Resolve strings registered with msg into the active locale with General Translation gt-react. API reference for useMessages. +description: Resolve strings registered with msg into the active locale. API reference for useMessages. --- diff --git a/docs/en-US/react/reference/hooks/use-region-selector.mdx b/docs/en-US/react/reference/hooks/use-region-selector.mdx index 110dda740..a3bff12df 100644 --- a/docs/en-US/react/reference/hooks/use-region-selector.mdx +++ b/docs/en-US/react/reference/hooks/use-region-selector.mdx @@ -1,7 +1,7 @@ --- title: useRegionSelector -description: Build a custom region switcher with General Translation gt-react. API reference for useRegionSelector. +description: Build a custom region switcher. API reference for useRegionSelector. --- diff --git a/docs/en-US/react/reference/hooks/use-region.mdx b/docs/en-US/react/reference/hooks/use-region.mdx index 3fc40a648..b1a7ce876 100644 --- a/docs/en-US/react/reference/hooks/use-region.mdx +++ b/docs/en-US/react/reference/hooks/use-region.mdx @@ -1,7 +1,7 @@ --- title: useRegion -description: Read the active region with General Translation gt-react. API reference for useRegion. +description: Read the active region. API reference for useRegion. --- diff --git a/docs/en-US/react/reference/hooks/use-set-locale.mdx b/docs/en-US/react/reference/hooks/use-set-locale.mdx index 527ab45a7..18763bf05 100644 --- a/docs/en-US/react/reference/hooks/use-set-locale.mdx +++ b/docs/en-US/react/reference/hooks/use-set-locale.mdx @@ -1,7 +1,7 @@ --- title: useSetLocale -description: Change the active locale with General Translation gt-react. API reference for useSetLocale. +description: Change the active locale. API reference for useSetLocale. --- diff --git a/docs/en-US/react/reference/hooks/use-set-region.mdx b/docs/en-US/react/reference/hooks/use-set-region.mdx index 165157489..00dcf1ac6 100644 --- a/docs/en-US/react/reference/hooks/use-set-region.mdx +++ b/docs/en-US/react/reference/hooks/use-set-region.mdx @@ -1,7 +1,7 @@ --- title: useSetRegion -description: Change the active region with General Translation gt-react. API reference for useSetRegion. +description: Change the active region. API reference for useSetRegion. --- diff --git a/docs/en-US/react/reference/hooks/use-translations.mdx b/docs/en-US/react/reference/hooks/use-translations.mdx index 8edc0203b..50a4f2318 100644 --- a/docs/en-US/react/reference/hooks/use-translations.mdx +++ b/docs/en-US/react/reference/hooks/use-translations.mdx @@ -1,7 +1,7 @@ --- title: useTranslations -description: Look up string translations from a dictionary by id with General Translation gt-react. API reference for useTranslations. +description: Look up string translations from a dictionary by id. API reference for useTranslations. --- diff --git a/docs/en-US/react/reference/lint-rules.mdx b/docs/en-US/react/reference/lint-rules.mdx index 25504830c..3d4780345 100644 --- a/docs/en-US/react/reference/lint-rules.mdx +++ b/docs/en-US/react/reference/lint-rules.mdx @@ -1,7 +1,7 @@ --- title: Lint rules -description: Reference for the General Translation React Core linter rules that keep translatable content static and correct. API reference for the React Core linter rules. +description: Keep translatable content static and correct with React Core linter rules. Reference for React Core linter rules. --- diff --git a/docs/en-US/react/reference/types/dictionary-translation-options.mdx b/docs/en-US/react/reference/types/dictionary-translation-options.mdx index a6449c532..a7e8675c5 100644 --- a/docs/en-US/react/reference/types/dictionary-translation-options.mdx +++ b/docs/en-US/react/reference/types/dictionary-translation-options.mdx @@ -1,7 +1,7 @@ --- title: DictionaryTranslationOptions -description: Options for passing variables to dictionary entries with General Translation gt-react. API reference for DictionaryTranslationOptions. +description: Options for passing variables to dictionary entries. API reference for DictionaryTranslationOptions. --- diff --git a/docs/en-US/react/reference/types/inline-translation-options.mdx b/docs/en-US/react/reference/types/inline-translation-options.mdx index 80cd10b53..68c6bcbe1 100644 --- a/docs/en-US/react/reference/types/inline-translation-options.mdx +++ b/docs/en-US/react/reference/types/inline-translation-options.mdx @@ -1,7 +1,7 @@ --- title: InlineTranslationOptions -description: Options for passing variables and metadata to inline string translations with General Translation gt-react. API reference for InlineTranslationOptions. +description: Options for passing variables and metadata to inline string translations. API reference for InlineTranslationOptions. --- diff --git a/scripts/test-validate-docs-structure.ts b/scripts/test-validate-docs-structure.ts index 62f194656..7408a4ae7 100644 --- a/scripts/test-validate-docs-structure.ts +++ b/scripts/test-validate-docs-structure.ts @@ -107,6 +107,43 @@ assertEqual( 'rejects a lowercase navigation title' ); +const componentPath = 'react/reference/components/t.mdx'; +const bareComponentTitle = new Map(repositoryFiles); +bareComponentTitle.set( + componentPath, + (bareComponentTitle.get(componentPath) ?? '').replace( + 'title: ""', + 'title: T' + ) +); +assertEqual( + hasFinding( + validateDocsStructure(bareComponentTitle), + componentPath, + 'title must use a quoted JSX tag' + ), + true, + 'rejects a bare React component title' +); + +const incompleteComponentDescription = new Map(repositoryFiles); +incompleteComponentDescription.set( + componentPath, + (incompleteComponentDescription.get(componentPath) ?? '').replace( + 'API reference for the component.', + 'API reference for T.' + ) +); +assertEqual( + hasFinding( + validateDocsStructure(incompleteComponentDescription), + componentPath, + 'description must include "API reference for the component."' + ), + true, + 'rejects incomplete React component search metadata' +); + const reorderedRoots = replaceMeta(repositoryFiles, 'meta.json', (meta) => { const pages = meta.pages as string[]; [pages[0], pages[1]] = [pages[1]!, pages[0]!]; @@ -121,6 +158,27 @@ assertEqual( 'rejects reordered top-level sections' ); +const missingOverviewSection = replaceMeta( + repositoryFiles, + 'overview/meta.json', + (meta) => { + const pages = meta.pages as string[]; + const googleDriveIndex = pages.findIndex((page) => + page.startsWith('[Google Drive]') + ); + pages.splice(googleDriveIndex, 1); + } +); +assertEqual( + hasFinding( + validateDocsStructure(missingOverviewSection), + 'overview/meta.json', + 'must link to the "Google Drive" section from integrations/meta.json' + ), + true, + 'rejects an integration section omitted from Overview' +); + const staleEntry = replaceMeta( repositoryFiles, 'node/guides/meta.json', diff --git a/scripts/validate-docs-structure.ts b/scripts/validate-docs-structure.ts index e6988664c..7960e090b 100644 --- a/scripts/validate-docs-structure.ts +++ b/scripts/validate-docs-structure.ts @@ -50,6 +50,11 @@ export type StructureFinding = Readonly<{ message: string; }>; +type CrossSectionLink = Readonly<{ + title: string; + path: string; +}>; + function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value); } @@ -79,6 +84,32 @@ function getPages(meta: Record): readonly string[] | undefined return meta.pages; } +function parseCrossSectionLink(entry: string): CrossSectionLink | undefined { + const match = /^\[([^\]]+)\]\((\/docs\/[^)]+)\)$/.exec(entry); + if (!match?.[1] || !match[2]) return undefined; + return { title: match[1], path: match[2] }; +} + +function getFrontmatterValue( + content: string, + key: string +): string | undefined { + const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)?.[1]; + if (!frontmatter) return undefined; + + const match = new RegExp(`^${key}:\\s*(.+?)\\s*$`, 'm').exec(frontmatter); + const value = match?.[1]; + if (!value) return undefined; + + if ( + (value.startsWith('"') && value.endsWith('"')) || + (value.startsWith("'") && value.endsWith("'")) + ) { + return value.slice(1, -1); + } + return value; +} + function findEntryCandidates( files: ReadonlyMap, metaPath: string, @@ -231,6 +262,34 @@ export function validateDocsStructure( } } + for (const [path, content] of files) { + if ( + !/^react\/(?:.+\/)?reference\/components\/[^/]+\.(?:md|mdx)$/.test( + path + ) + ) { + continue; + } + + const title = getFrontmatterValue(content, 'title'); + if (!title || !/^<[A-Za-z_$][A-Za-z0-9_$]*>$/.test(title)) { + addFinding( + path, + 'React component reference title must use a quoted JSX tag such as "".' + ); + continue; + } + + const description = getFrontmatterValue(content, 'description'); + const expectedReference = `API reference for the ${title} component.`; + if (!description?.includes(expectedReference)) { + addFinding( + path, + `React component description must include "${expectedReference}"` + ); + } + } + for (const path of files.keys()) { if (!/\.(md|mdx)$/.test(path)) continue; const parentDirectory = posix.dirname(path); @@ -315,6 +374,43 @@ export function validateDocsStructure( } } + const overviewMetaPath = 'overview/meta.json'; + const overviewMeta = metaByPath.get(overviewMetaPath); + const overviewPages = overviewMeta && getPages(overviewMeta); + if (overviewPages) { + const overviewLinks = overviewPages + .map(parseCrossSectionLink) + .filter((link): link is CrossSectionLink => link !== undefined); + + for (const root of ['platform', 'integrations'] as const) { + const rootMetaPath = `${root}/meta.json`; + const rootMeta = metaByPath.get(rootMetaPath); + const rootPages = rootMeta && getPages(rootMeta); + if (!rootPages) continue; + + for (const page of rootPages) { + if (!page.startsWith('./')) continue; + const childBase = resolveEntryBase(rootMetaPath, page); + const childMetaPath = `${childBase}/meta.json`; + const childMeta = metaByPath.get(childMetaPath); + if (!childMeta || typeof childMeta.title !== 'string') continue; + + const expectedPathPrefix = `/docs/${childBase}/`; + const hasLink = overviewLinks.some( + (link) => + link.title === childMeta.title && + link.path.startsWith(expectedPathPrefix) + ); + if (!hasLink) { + addFinding( + overviewMetaPath, + `Overview sidebar must link to the "${childMeta.title}" section from ${rootMetaPath}.` + ); + } + } + } + } + for (const [metaPath, meta] of metaByPath) { if (meta.root !== true) continue; const directory = metadataDirectory(metaPath); @@ -341,7 +437,7 @@ export function collectDocsFiles(root: string): Map { const relativePath = relative(root, absolutePath).split(sep).join('/'); files.set( relativePath, - entry.name === 'meta.json' ? readFileSync(absolutePath, 'utf8') : '' + readFileSync(absolutePath, 'utf8') ); } } From e333f7fe361fd00c8211fb2eed2b0ce40d8dc90c Mon Sep 17 00:00:00 2001 From: taylor-fang Date: Thu, 6 Aug 2026 20:16:53 -0700 Subject: [PATCH 08/13] docs: more clear and comprehensive React guides and formatting references (#444) Co-authored-by: Taylor Fang --- DOCS-SKILL.md | 4 + docs/en-US/cli/guides/branching.mdx | 2 +- .../formatting/format-currency.mdx | 27 ++- .../formatting/format-date-time.mdx | 22 +- .../formatting/format-list-to-parts.mdx | 5 +- .../formatting/format-list.mdx | 5 +- .../formatting/format-num.mdx | 23 +- .../format-relative-time-from-date.mdx | 10 +- .../formatting/format-relative-time.mdx | 12 +- .../formatting/format-currency.mdx | 25 +- .../formatting/format-date-time.mdx | 23 +- .../formatting/format-list-to-parts.mdx | 3 +- .../formatting/format-list.mdx | 3 +- .../formatting/format-num.mdx | 26 ++- .../format-relative-time-from-date.mdx | 4 +- .../formatting/format-relative-time.mdx | 6 +- .../reference/project/create-branch.mdx | 2 +- docs/en-US/react/guides/configuring.mdx | 26 +-- .../react/guides/formatting-variables.mdx | 97 +++++++- .../guides/handling-plurals-and-branches.mdx | 51 +++- docs/en-US/react/guides/linting-your-code.mdx | 8 +- docs/en-US/react/guides/managing-locales.mdx | 167 +++++++++++-- .../react/guides/storing-translations.mdx | 4 +- docs/en-US/react/guides/translating-jsx.mdx | 4 +- .../react/guides/translating-strings.mdx | 2 +- .../guides/translating-with-dictionaries.mdx | 10 +- .../react/reference/components/branch.mdx | 4 +- .../react/reference/components/currency.mdx | 39 +++- .../react/reference/components/datetime.mdx | 36 ++- .../react/reference/components/derive.mdx | 4 +- .../reference/components/gt-provider.mdx | 220 ++++++++++++------ .../reference/components/locale-selector.mdx | 6 +- docs/en-US/react/reference/components/num.mdx | 37 ++- .../react/reference/components/plural.mdx | 4 +- .../reference/components/region-selector.mdx | 4 +- .../reference/components/relative-time.mdx | 16 +- docs/en-US/react/reference/components/t.mdx | 4 +- docs/en-US/react/reference/components/var.mdx | 4 +- .../react/reference/functions/declare-var.mdx | 4 +- .../react/reference/functions/decode-vars.mdx | 4 +- .../react/reference/functions/derive.mdx | 4 +- .../functions/get-translations-snapshot.mdx | 4 +- docs/en-US/react/reference/functions/msg.mdx | 4 +- .../react/reference/functions/t-function.mdx | 4 +- .../reference/hooks/use-default-locale.mdx | 4 +- docs/en-US/react/reference/hooks/use-gt.mdx | 4 +- .../reference/hooks/use-locale-direction.mdx | 4 +- .../reference/hooks/use-locale-properties.mdx | 4 +- .../reference/hooks/use-locale-selector.mdx | 8 +- .../react/reference/hooks/use-locale.mdx | 4 +- .../react/reference/hooks/use-locales.mdx | 4 +- .../react/reference/hooks/use-messages.mdx | 4 +- .../reference/hooks/use-region-selector.mdx | 4 +- .../react/reference/hooks/use-region.mdx | 4 +- .../react/reference/hooks/use-set-locale.mdx | 11 +- .../react/reference/hooks/use-set-region.mdx | 4 +- .../reference/hooks/use-translations.mdx | 4 +- scripts/test-validate-reference-links.ts | 19 ++ scripts/validate-reference-links.ts | 14 +- 59 files changed, 830 insertions(+), 239 deletions(-) diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md index 018c1d330..b17480407 100644 --- a/DOCS-SKILL.md +++ b/DOCS-SKILL.md @@ -521,6 +521,8 @@ Anatomy: 4. Detailed task sections (`##`): one section per sub-task, each with ordered steps. Name the exact buttons and pages in **bold**. Titles must be understandable and actionable. 5. Optional **What to use and when**: when a task offers two or more valid approaches, add a short decision list contrasting them (each bullet: the option in **bold**, then when to choose it) so the reader can pick quickly. Model this on the Next.js "What to use and when" bullets. +**Link named API details precisely.** When a Guide names a public prop, option, field, or parameter and the Reference documents that same public surface, link to its exact anchor rather than only the parent page. Require semantic API identity, not only a shared name: do not link a returned callback, framework wrapper, or package-specific field to a different standalone function, prop, or method. When no exact matching surface exists, leave the name unlinked or link the containing API with wording that makes the relationship clear. + *Example happy-path workflow (from the context guide):* ```text @@ -559,6 +561,8 @@ Use a consistent set of Guides where possible, in this order: Reference pages are **comprehensive, exact lookups** for a **technical audience**: cover every field, option, parameter, permission, command, flag, limit, error, and setting for the topic — including defaults and behavior — within a clear, predictable structure. **This is the one place to favor completeness over brevity.** The conciseness rule still governs *wording*, but never drop options, flags, edge cases, or defaults just to keep a page short. When in doubt here, document more. This is the exception to the general "keep it short" guidance that applies elsewhere in the docs. - **Write for developers.** Assume familiarity with the terminal, code, and the relevant language or framework; do not simplify away technical detail or restate basics covered in the Quickstart. +- **Place scope notes where they apply.** Keep API availability and framework scope near the intro. Put package, language, or framework context that only explains sample code immediately after the **Examples** heading, or directly before the first example code block it qualifies when the page has no Examples section. +- **Document external-standard options locally.** When a public API accepts options from an external standard such as `Intl`, document the commonly used and currently supported fields, accepted values, defaults, and important constraints on the Reference page. Retain a link to the upstream standard as the source for future additions and runtime updates; do not make readers leave the page to discover basic options. - **Lead with an overview table** that lists every item covered on the page (option, method, field, command, flag, endpoint), and **link each item name to its section on the same page** so a reader can jump straight to it. Model this on the Sanity plugin reference and the Next.js `generateMetadata` reference. For parameter/flag tables, use the column order Name, Description, Type, Optional, Default (see Lists vs. tables). This overview table replaces a separate bullet "table of contents". - **The overview table is for navigation and scanning only — it never replaces the detailed sections.** Every reference page still needs its full per-item sections *below* the table (each with an example, expected output, behavior, and notes). A page that is only a table is not finished. - **Then one section per item** (`##`, optionally grouped into subsections), in the **same order as the table**. **Each section must stand on its own:** the overview table is high-level navigation, but the reader should get *everything* about that item from its own section without going back to the table. Lead each section with a compact attribute line restating the item's key facts (for a field or parameter: **Type**, **Optional**/**Required**, and **Default** — the same values as its table row, in the format shown below), then give the full description, accepted values, side effects, error/permission behavior, and an example. Do not leave the type or default *only* in the table. Keep entries parallel in shape. diff --git a/docs/en-US/cli/guides/branching.mdx b/docs/en-US/cli/guides/branching.mdx index 9cebff4a1..a5c691acc 100644 --- a/docs/en-US/cli/guides/branching.mdx +++ b/docs/en-US/cli/guides/branching.mdx @@ -13,7 +13,7 @@ related: 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.* +*Note: Branching is a General Translation Cloud feature and requires the Starter plan. Without Starter, creating a non-default branch falls back to the default branch.* ## Enable branching [#enable] 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 index 9b3719be6..9d68e6bc8 100644 --- 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 @@ -60,12 +60,33 @@ The ISO 4217 currency code, such as `USD`, `EUR`, or `JPY`. **Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Optional** -Formatting configuration. Extends `Intl.NumberFormatOptions` with an additional `locales` field: +Formatting configuration. The table lists common currency options exposed by the published Core types and their effective Core defaults. See the [`Intl.NumberFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for supplemental standard and runtime-specific details. | Name | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| `locales` | Override locales for formatting. | `string \| string[]` | Yes | instance target locale | -| `style` | Number formatting style; defaults to currency formatting. | `string` | Yes | `'currency'` | +| `locales` | Override locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` | +| `style` | Number formatting style. `formatCurrency` supplies the currency style unless you override it. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'currency'` | +| `currency` | Currency code used by the formatter. The positional `currency` argument supplies this value unless you override it. | `string` | Yes | positional `currency` argument | +| `currencyDisplay` | How to display the currency. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Yes | `'symbol'` | +| `currencySign` | Currency sign to use. | `'standard' \| 'accounting'` | Yes | `'standard'` | +| `unit` | Unit identifier. Required when `style` is `'unit'`. | `string` | Yes | — | +| `unitDisplay` | How to display the unit. | `'short' \| 'narrow' \| 'long'` | Yes | `'short'` | +| `minimumFractionDigits` | Minimum fraction digits (0–100). | `number` | Yes | currency minor-unit digits; `0` with compact defaults | +| `maximumFractionDigits` | Maximum fraction digits (0–100), at least `minimumFractionDigits`. | `number` | Yes | currency minor-unit digits; `0` with compact defaults | +| `minimumSignificantDigits` | Minimum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `1` | +| `maximumSignificantDigits` | Maximum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `21`; `2` with compact defaults | +| `roundingPriority` | How fraction- and significant-digit settings interact. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'`; `'morePrecision'` with compact defaults | +| `roundingMode` | Rounding mode. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` | +| `roundingIncrement` | Rounding increment. Non-default values require equal effective minimum and maximum fraction digits and cannot be combined with significant-digit rounding or a non-`'auto'` `roundingPriority`. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` | +| `useGrouping` | Whether and when to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact defaults | +| `notation` | Number notation format. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` | +| `compactDisplay` | Compact notation display style. | `'short' \| 'long'` | Yes | `'short'` | +| `signDisplay` | When to display the sign. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Yes | `'auto'` | +| `trailingZeroDisplay` | Whether to display trailing zeros. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` | + +When `notation: 'compact'` is set without any fraction- or significant-digit option, the effective digit defaults are `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1`, and `maximumSignificantDigits: 2`. In that case, `roundingPriority` defaults to `'morePrecision'` and `useGrouping` defaults to `'min2'`. Setting `style: 'unit'` also requires a valid `unit`. ## Returns [#returns] diff --git a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-date-time.mdx b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-date-time.mdx index 27cd89bb2..e35b37634 100644 --- a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-date-time.mdx +++ b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-date-time.mdx @@ -30,11 +30,11 @@ formatDateTime( ): string ``` -*Note: `formatDateTime` runs locally using `Intl.DateTimeFormat` and does not require an API key. It uses the instance's rendering locales by default; pass `locales` to override. For formatting without a `GT` instance, see the standalone [`formatDateTime`](/docs/platform/core/reference/utility-functions/formatting/format-date-time).* +*Note: `formatDateTime` runs locally using `Intl.DateTimeFormat` and does not require an API key. It uses the instance's target locale by default, then falls back to the source locale and `en`; pass `locales` to override. For formatting without a `GT` instance, see the standalone [`formatDateTime`](/docs/platform/core/reference/utility-functions/formatting/format-date-time).* ## How it works [#how-it-works] -- **Locale resolution.** By default the method formats for the instance's locales. Pass `locales` in the options to override them for a single call. +- **Locale resolution.** By default the method formats for the instance's target locale, falling back to the source locale and then `en`. Pass `locales` in the options to override for a single call. - **Intl-backed.** Formatting is delegated to the browser-native [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), so all standard `Intl.DateTimeFormatOptions` are supported. - **Time zones.** Time zones are handled correctly when a `timeZone` is specified; otherwise the runtime's local time zone is used. @@ -55,32 +55,34 @@ The `Date` object to format. **Type** `{ locales?: string | string[] } & Intl.DateTimeFormatOptions` · **Optional** -Formatting configuration. Extends `Intl.DateTimeFormatOptions` with an additional `locales` field: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.DateTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) for supplemental standard and runtime-specific details. | Name | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| `locales` | Override locales for formatting. | `string \| string[]` | Yes | instance locales | +| `locales` | Override locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | | `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | | `dateStyle` | Overall date formatting style. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | | `timeStyle` | Overall time formatting style. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | | `weekday` | Weekday representation. | `'long' \| 'short' \| 'narrow'` | Yes | — | | `era` | Era representation. | `'long' \| 'short' \| 'narrow'` | Yes | — | -| `year` | Year representation. | `'numeric' \| '2-digit'` | Yes | — | -| `month` | Month representation. | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes | — | -| `day` | Day representation. | `'numeric' \| '2-digit'` | Yes | — | +| `year` | Year representation. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | +| `month` | Month representation. | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes | `'numeric'` when no styles or components are set | +| `day` | Day representation. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | | `dayPeriod` | Day period formatting (morning, afternoon, etc.). | `'narrow' \| 'short' \| 'long'` | Yes | — | | `hour` | Hour representation. | `'numeric' \| '2-digit'` | Yes | — | | `minute` | Minute representation. | `'numeric' \| '2-digit'` | Yes | — | | `second` | Second representation. | `'numeric' \| '2-digit'` | Yes | — | | `fractionalSecondDigits` | Number of fractional second digits. | `1 \| 2 \| 3` | Yes | — | | `timeZoneName` | Time zone name format. | `'long' \| 'short' \| 'longOffset' \| 'shortOffset' \| 'longGeneric' \| 'shortGeneric'` | Yes | — | -| `timeZone` | IANA time zone identifier. | `string` | Yes | runtime time zone | -| `hour12` | Whether to use 12-hour time format. | `boolean` | Yes | — | -| `hourCycle` | Hour cycle preference. | `'h11' \| 'h12' \| 'h23' \| 'h24'` | Yes | — | +| `timeZone` | IANA time zone name or supported UTC offset identifier. | `string` | Yes | runtime time zone | +| `hour12` | Whether to use 12-hour time format. | `boolean` | Yes | locale-dependent | +| `hourCycle` | Hour cycle preference. | `'h11' \| 'h12' \| 'h23' \| 'h24'` | Yes | locale-dependent | | `calendar` | Calendar system to use. | `string` | Yes | `'gregory'` | | `numberingSystem` | Numbering system for digits. | `string` | Yes | `'latn'` | | `formatMatcher` | Format matching algorithm. | `'basic' \| 'best fit'` | Yes | `'best fit'` | +`dateStyle` and `timeStyle` can be combined with each other, but not with individual date-time component options such as `year`, `month`, or `hour`. `hour12` overrides `hourCycle`, and `dayPeriod` only affects 12-hour cycles. Core sets `calendar: 'gregory'` and `numberingSystem: 'latn'`; upstream `Intl.DateTimeFormat` otherwise chooses both from the locale. + ## Returns [#returns] **Type** `string` diff --git a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-list-to-parts.mdx b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-list-to-parts.mdx index 099a31596..dfb89b5d5 100644 --- a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-list-to-parts.mdx +++ b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-list-to-parts.mdx @@ -53,11 +53,12 @@ The array of items to format. Items may be any type; non-string items are preser **Type** `{ locales?: string | string[] } & Intl.ListFormatOptions` · **Optional** -Formatting configuration. Extends `Intl.ListFormatOptions` with an additional `locales` field: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.ListFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#options) for supplemental standard and runtime-specific details. | Name | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| `locales` | Override locales for formatting. | `string \| string[]` | Yes | instance target locale | +| `locales` | Override locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | | `type` | List formatting type. | `'conjunction' \| 'disjunction' \| 'unit'` | Yes | `'conjunction'` | | `style` | List formatting style. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | 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 index cc5710cd0..66b0db513 100644 --- 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 @@ -52,11 +52,12 @@ The list of items to join into a single string. **Type** `{ locales?: string | string[] } & Intl.ListFormatOptions` · **Optional** -Formatting configuration. Extends `Intl.ListFormatOptions` with an additional `locales` field: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.ListFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#options) for supplemental standard and runtime-specific details. | Name | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| `locales` | Override locales for formatting. | `string \| string[]` | Yes | instance target locale | +| `locales` | Override locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | | `type` | List formatting type. | `'conjunction' \| 'disjunction' \| 'unit'` | Yes | `'conjunction'` | | `style` | List formatting style. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | diff --git a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-num.mdx b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-num.mdx index ab570427b..d26289b5f 100644 --- a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-num.mdx +++ b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-num.mdx @@ -55,11 +55,13 @@ The number to format. **Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Optional** -Formatting configuration. Extends `Intl.NumberFormatOptions` with an additional `locales` field: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.NumberFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for supplemental standard and runtime-specific details. | Name | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| `locales` | Override locales for formatting. | `string \| string[]` | Yes | instance target locale | +| `locales` | Override locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` | | `style` | Number formatting style. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'decimal'` | | `currency` | Currency code (required when `style` is `'currency'`). | `string` | Yes | — | | `currencyDisplay` | How to display the currency. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Yes | `'symbol'` | @@ -67,18 +69,21 @@ Formatting configuration. Extends `Intl.NumberFormatOptions` with an additional | `unit` | Unit identifier (required when `style` is `'unit'`). | `string` | Yes | — | | `unitDisplay` | How to display the unit. | `'short' \| 'narrow' \| 'long'` | Yes | `'short'` | | `minimumIntegerDigits` | Minimum number of integer digits (1–21). | `number` | Yes | `1` | -| `minimumFractionDigits` | Minimum number of fraction digits (0–20). | `number` | Yes | — | -| `maximumFractionDigits` | Maximum number of fraction digits (0–20). | `number` | Yes | — | -| `minimumSignificantDigits` | Minimum significant digits (1–21). | `number` | Yes | — | -| `maximumSignificantDigits` | Maximum significant digits (1–21). | `number` | Yes | — | -| `useGrouping` | Whether to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'` | +| `minimumFractionDigits` | Minimum fraction digits (0–100). The style affects the default. | `number` | Yes | `0` for decimal/percent; currency minor-unit digits for currency; `0` with compact defaults | +| `maximumFractionDigits` | Maximum fraction digits (0–100). The style and minimum affect the default. | `number` | Yes | `3` for decimal; `0` for percent; currency minor-unit digits for currency; `0` with compact defaults | +| `minimumSignificantDigits` | Minimum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `1` | +| `maximumSignificantDigits` | Maximum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `21`; `2` with compact defaults | +| `roundingPriority` | How fraction- and significant-digit settings interact. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'`; `'morePrecision'` with compact defaults | | `notation` | Number notation format. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` | | `compactDisplay` | Compact notation display style. | `'short' \| 'long'` | Yes | `'short'` | -| `signDisplay` | When to display the sign. | `'auto' \| 'never' \| 'always' \| 'exceptZero'` | Yes | `'auto'` | +| `useGrouping` | Whether and when to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact notation | +| `signDisplay` | When to display the sign. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Yes | `'auto'` | | `roundingMode` | Rounding mode. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` | -| `roundingIncrement` | Rounding increment. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100` | Yes | `1` | +| `roundingIncrement` | Rounding increment. Non-default values require equal effective minimum and maximum fraction digits and cannot be combined with significant-digit rounding or a non-`'auto'` `roundingPriority`. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` | | `trailingZeroDisplay` | Whether to display trailing zeros. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` | +When `notation: 'compact'` is set without any fraction- or significant-digit option, the effective digit defaults are `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1`, and `maximumSignificantDigits: 2`. In that case, `roundingPriority` defaults to `'morePrecision'` and `useGrouping` defaults to `'min2'`. + ## Returns [#returns] **Type** `string` diff --git a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date.mdx b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date.mdx index b1d34b43c..1d20af3bb 100644 --- a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date.mdx +++ b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date.mdx @@ -33,13 +33,13 @@ formatRelativeTimeFromDate( ): string ``` -*Note: `formatRelativeTimeFromDate` runs locally using `Intl.RelativeTimeFormat` and does not require an API key. It falls back to the instance's rendering locales when `locales` is omitted. For formatting without a `GT` instance, see the standalone [`formatRelativeTimeFromDate`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date).* +*Note: `formatRelativeTimeFromDate` runs locally using `Intl.RelativeTimeFormat` and does not require an API key. It uses the instance's target locale by default, then falls back to the source locale and `en`. For formatting without a `GT` instance, see the standalone [`formatRelativeTimeFromDate`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date).* ## How it works [#how-it-works] - **Automatic unit selection.** The method computes the difference between `date` and `baseDate` and picks the best unit (seconds, minutes, hours, days, and so on). - **Base date.** Comparison is against `baseDate`, which defaults to `new Date()` (the current time). -- **Locale resolution.** When `locales` is omitted, the method falls back to the instance's rendering locales. +- **Locale resolution.** When `locales` is omitted, the method uses the instance's target locale, then the source locale and `en`. - **Defaults.** `numeric` defaults to `'auto'` and `style` defaults to `'long'`. ## Parameters [#parameters] @@ -59,16 +59,18 @@ The date to format relative to `baseDate`. **Type** `{ locales?: string | string[]; baseDate?: Date } & Omit` · **Optional** -Formatting configuration: +Formatting configuration. The table lists `baseDate`, `locales`, and common options exposed by the published Core types, with their effective Core defaults. See the [`Intl.RelativeTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for supplemental standard and runtime-specific details. | Name | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| `locales` | Locales for formatting. Falls back to the instance's rendering locales. | `string \| string[]` | Yes | instance locales | +| `locales` | Locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | | `baseDate` | The base date for comparison. | `Date` | Yes | `new Date()` | | `numeric` | Whether to always use numeric output. | `'always' \| 'auto'` | Yes | `'auto'` | | `style` | The length of the output. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | | `localeMatcher` | The locale matching algorithm to use. | `'best fit' \| 'lookup'` | Yes | `'best fit'` | +`baseDate` is a Core-only field and is not passed to `Intl.RelativeTimeFormat`. Core also changes the upstream `numeric` default from `'always'` to `'auto'`. + ## Returns [#returns] **Type** `string` diff --git a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time.mdx b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time.mdx index 07c290a67..3c399780f 100644 --- a/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time.mdx +++ b/docs/en-US/platform/core/reference/gt-class-methods/formatting/format-relative-time.mdx @@ -31,11 +31,11 @@ formatRelativeTime( ): string ``` -*Note: `formatRelativeTime` runs locally using `Intl.RelativeTimeFormat` and does not require an API key. It falls back to the instance's rendering locales when `locales` is omitted. For formatting without a `GT` instance, see the standalone [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time).* +*Note: `formatRelativeTime` runs locally using `Intl.RelativeTimeFormat` and does not require an API key. It uses the instance's target locale by default, then falls back to the source locale and `en`. For formatting without a `GT` instance, see the standalone [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time).* ## How it works [#how-it-works] -- **Locale resolution.** When `locales` is omitted, the method falls back to the instance's rendering locales. +- **Locale resolution.** When `locales` is omitted, the method uses the instance's target locale, then the source locale and `en`. - **Intl-backed.** Formatting is delegated to the browser-native [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). - **Defaults.** `numeric` defaults to `'auto'` (so `-1 day` becomes "yesterday" rather than "1 day ago") and `style` defaults to `'long'`. @@ -57,21 +57,23 @@ The relative time value. Negative values are in the past; positive values are in **Type** `Intl.RelativeTimeFormatUnit` · **Required** -The unit of time: `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, or `'year'`. +The unit of time. Singular and plural forms are accepted: `'second'`/`'seconds'`, `'minute'`/`'minutes'`, `'hour'`/`'hours'`, `'day'`/`'days'`, `'week'`/`'weeks'`, `'month'`/`'months'`, `'quarter'`/`'quarters'`, and `'year'`/`'years'`. ### `options` [#options] **Type** `{ locales?: string | string[] } & Omit` · **Optional** -Formatting configuration: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.RelativeTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for supplemental standard and runtime-specific details. | Name | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| `locales` | Locales for formatting. Falls back to the instance's rendering locales. | `string \| string[]` | Yes | instance locales | +| `locales` | Locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | | `numeric` | Whether to always use numeric output. | `'always' \| 'auto'` | Yes | `'auto'` | | `style` | The length of the output. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | | `localeMatcher` | The locale matching algorithm to use. | `'best fit' \| 'lookup'` | Yes | `'best fit'` | +Core changes the upstream `numeric` default from `'always'` to `'auto'`; the other standard defaults come from `Intl.RelativeTimeFormat`. + ## Returns [#returns] **Type** `string` diff --git a/docs/en-US/platform/core/reference/utility-functions/formatting/format-currency.mdx b/docs/en-US/platform/core/reference/utility-functions/formatting/format-currency.mdx index 985f60646..c4b8eb752 100644 --- a/docs/en-US/platform/core/reference/utility-functions/formatting/format-currency.mdx +++ b/docs/en-US/platform/core/reference/utility-functions/formatting/format-currency.mdx @@ -58,12 +58,33 @@ The ISO 4217 currency code, such as `USD`, `EUR`, or `JPY`. **Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Optional** · **Default** `{}` -Formatting configuration: +Formatting configuration. The table lists common currency options exposed by the published Core types and their effective Core defaults. See the [`Intl.NumberFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for supplemental standard and runtime-specific details. | Property | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | | `locales` | Locale(s) for formatting. | `string \| string[]` | Yes | `en` | -| `style` | Number formatting style; defaults to currency formatting. | `string` | Yes | `'currency'` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` | +| `style` | Number formatting style. `formatCurrency` supplies the currency style unless you override it. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'currency'` | +| `currency` | Currency code used by the formatter. The positional `currency` argument supplies this value unless you override it. | `string` | Yes | positional `currency` argument | +| `currencyDisplay` | How to display the currency. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Yes | `'symbol'` | +| `currencySign` | Currency sign to use. | `'standard' \| 'accounting'` | Yes | `'standard'` | +| `unit` | Unit identifier. Required when `style` is `'unit'`. | `string` | Yes | — | +| `unitDisplay` | How to display the unit. | `'short' \| 'narrow' \| 'long'` | Yes | `'short'` | +| `minimumFractionDigits` | Minimum fraction digits (0–100). | `number` | Yes | currency minor-unit digits; `0` with compact defaults | +| `maximumFractionDigits` | Maximum fraction digits (0–100), at least `minimumFractionDigits`. | `number` | Yes | currency minor-unit digits; `0` with compact defaults | +| `minimumSignificantDigits` | Minimum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `1` | +| `maximumSignificantDigits` | Maximum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `21`; `2` with compact defaults | +| `roundingPriority` | How fraction- and significant-digit settings interact. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'`; `'morePrecision'` with compact defaults | +| `roundingMode` | Rounding mode. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` | +| `roundingIncrement` | Rounding increment. Non-default values require equal effective minimum and maximum fraction digits and cannot be combined with significant-digit rounding or a non-`'auto'` `roundingPriority`. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` | +| `useGrouping` | Whether and when to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact defaults | +| `notation` | Number notation format. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` | +| `compactDisplay` | Compact notation display style. | `'short' \| 'long'` | Yes | `'short'` | +| `signDisplay` | When to display the sign. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Yes | `'auto'` | +| `trailingZeroDisplay` | Whether to display trailing zeros. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` | + +When `notation: 'compact'` is set without any fraction- or significant-digit option, the effective digit defaults are `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1`, and `maximumSignificantDigits: 2`. In that case, `roundingPriority` defaults to `'morePrecision'` and `useGrouping` defaults to `'min2'`. Setting `style: 'unit'` also requires a valid `unit`. ## Returns [#returns] diff --git a/docs/en-US/platform/core/reference/utility-functions/formatting/format-date-time.mdx b/docs/en-US/platform/core/reference/utility-functions/formatting/format-date-time.mdx index 954c558d7..110007831 100644 --- a/docs/en-US/platform/core/reference/utility-functions/formatting/format-date-time.mdx +++ b/docs/en-US/platform/core/reference/utility-functions/formatting/format-date-time.mdx @@ -55,22 +55,33 @@ The `Date` object to format. **Type** `{ locales?: string | string[] } & Intl.DateTimeFormatOptions` · **Optional** · **Default** `{}` -Formatting configuration. Any [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) option is accepted in addition to `locales`. Common fields: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.DateTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) for supplemental standard and runtime-specific details. | Property | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | | `locales` | Locale(s) for formatting. Tried in order when an array is passed. | `string \| string[]` | Yes | `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | | `dateStyle` | Overall date formatting style. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | | `timeStyle` | Overall time formatting style. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | | `weekday` | Weekday representation. | `'long' \| 'short' \| 'narrow'` | Yes | — | -| `year` | Year representation. | `'numeric' \| '2-digit'` | Yes | — | -| `month` | Month representation. | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes | — | -| `day` | Day representation. | `'numeric' \| '2-digit'` | Yes | — | +| `era` | Era representation. | `'long' \| 'short' \| 'narrow'` | Yes | — | +| `year` | Year representation. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | +| `month` | Month representation. | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes | `'numeric'` when no styles or components are set | +| `day` | Day representation. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | +| `dayPeriod` | Day-period width for 12-hour cycles. | `'narrow' \| 'short' \| 'long'` | Yes | — | | `hour` | Hour representation. | `'numeric' \| '2-digit'` | Yes | — | | `minute` | Minute representation. | `'numeric' \| '2-digit'` | Yes | — | | `second` | Second representation. | `'numeric' \| '2-digit'` | Yes | — | -| `timeZone` | IANA time zone identifier. | `string` | Yes | — | -| `hour12` | Whether to use 12-hour time format. | `boolean` | Yes | — | +| `fractionalSecondDigits` | Number of fractional second digits. | `1 \| 2 \| 3` | Yes | — | +| `timeZoneName` | Time zone name format. | `'long' \| 'short' \| 'longOffset' \| 'shortOffset' \| 'longGeneric' \| 'shortGeneric'` | Yes | — | +| `timeZone` | IANA time zone name or supported UTC offset identifier. | `string` | Yes | runtime time zone | +| `hour12` | Whether to use 12-hour time format. | `boolean` | Yes | locale-dependent | +| `hourCycle` | Hour cycle preference. | `'h11' \| 'h12' \| 'h23' \| 'h24'` | Yes | locale-dependent | +| `calendar` | Calendar system to use. | `string` | Yes | `'gregory'` | +| `numberingSystem` | Numbering system for digits. | `string` | Yes | `'latn'` | +| `formatMatcher` | Format matching algorithm. | `'basic' \| 'best fit'` | Yes | `'best fit'` | + +`dateStyle` and `timeStyle` can be combined with each other, but not with individual date-time component options such as `year`, `month`, or `hour`. `hour12` overrides `hourCycle`, and `dayPeriod` only affects 12-hour cycles. Core sets `calendar: 'gregory'` and `numberingSystem: 'latn'`; upstream `Intl.DateTimeFormat` otherwise chooses both from the locale. ## Returns [#returns] diff --git a/docs/en-US/platform/core/reference/utility-functions/formatting/format-list-to-parts.mdx b/docs/en-US/platform/core/reference/utility-functions/formatting/format-list-to-parts.mdx index 7f7d6ead5..f24103e89 100644 --- a/docs/en-US/platform/core/reference/utility-functions/formatting/format-list-to-parts.mdx +++ b/docs/en-US/platform/core/reference/utility-functions/formatting/format-list-to-parts.mdx @@ -55,11 +55,12 @@ The array of items to format. Items of any type are supported; non-string items **Type** `{ locales?: string | string[] } & Intl.ListFormatOptions` · **Optional** · **Default** `{}` -Formatting configuration: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.ListFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#options) for supplemental standard and runtime-specific details. | Property | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | | `locales` | Locale(s) for formatting. | `string \| string[]` | Yes | `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | | `type` | List formatting type. | `'conjunction' \| 'disjunction' \| 'unit'` | Yes | `'conjunction'` | | `style` | List formatting style. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | diff --git a/docs/en-US/platform/core/reference/utility-functions/formatting/format-list.mdx b/docs/en-US/platform/core/reference/utility-functions/formatting/format-list.mdx index 5fd5ce575..784f38a6e 100644 --- a/docs/en-US/platform/core/reference/utility-functions/formatting/format-list.mdx +++ b/docs/en-US/platform/core/reference/utility-functions/formatting/format-list.mdx @@ -52,11 +52,12 @@ The list of items to join into a single string. **Type** `{ locales?: string | string[] } & Intl.ListFormatOptions` · **Optional** · **Default** `{}` -Formatting configuration: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.ListFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#options) for supplemental standard and runtime-specific details. | Property | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | | `locales` | Locale(s) for formatting. | `string \| string[]` | Yes | `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | | `type` | List formatting type. | `'conjunction' \| 'disjunction' \| 'unit'` | Yes | `'conjunction'` | | `style` | List formatting style. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | diff --git a/docs/en-US/platform/core/reference/utility-functions/formatting/format-num.mdx b/docs/en-US/platform/core/reference/utility-functions/formatting/format-num.mdx index 9a0c91320..55e2209a3 100644 --- a/docs/en-US/platform/core/reference/utility-functions/formatting/format-num.mdx +++ b/docs/en-US/platform/core/reference/utility-functions/formatting/format-num.mdx @@ -54,18 +54,34 @@ The numeric value to format. **Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Optional** · **Default** `{}` -Formatting configuration. Any [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) option is accepted in addition to `locales`. The most common fields: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.NumberFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for supplemental standard and runtime-specific details. | Property | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | | `locales` | Locale(s) for formatting. Tried in order when an array is passed. | `string \| string[]` | Yes | `en` | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` | | `style` | Number formatting style. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'decimal'` | | `currency` | Currency code (required when `style` is `'currency'`). | `string` | Yes | — | -| `minimumIntegerDigits` | Minimum number of integer digits (1–21). | `number` | Yes | — | -| `minimumFractionDigits` | Minimum number of fraction digits (0–20). | `number` | Yes | — | -| `maximumFractionDigits` | Maximum number of fraction digits (0–20). | `number` | Yes | — | -| `useGrouping` | Whether to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'` | +| `currencyDisplay` | How to display the currency. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Yes | `'symbol'` | +| `currencySign` | Currency sign to use. | `'standard' \| 'accounting'` | Yes | `'standard'` | +| `unit` | Unit identifier (required when `style` is `'unit'`). | `string` | Yes | — | +| `unitDisplay` | How to display the unit. | `'short' \| 'narrow' \| 'long'` | Yes | `'short'` | +| `minimumIntegerDigits` | Minimum number of integer digits (1–21). | `number` | Yes | `1` | +| `minimumFractionDigits` | Minimum fraction digits (0–100). The style affects the default. | `number` | Yes | `0` for decimal/percent; currency minor-unit digits for currency; `0` with compact defaults | +| `maximumFractionDigits` | Maximum fraction digits (0–100). The style and minimum affect the default. | `number` | Yes | `3` for decimal; `0` for percent; currency minor-unit digits for currency; `0` with compact defaults | +| `minimumSignificantDigits` | Minimum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `1` | +| `maximumSignificantDigits` | Maximum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `21`; `2` with compact defaults | +| `roundingPriority` | How fraction- and significant-digit settings interact. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'`; `'morePrecision'` with compact defaults | | `notation` | Number notation format. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` | +| `compactDisplay` | Compact notation display style. | `'short' \| 'long'` | Yes | `'short'` | +| `useGrouping` | Whether and when to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact notation | +| `signDisplay` | When to display the sign. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Yes | `'auto'` | +| `roundingMode` | Rounding mode. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` | +| `roundingIncrement` | Rounding increment. Non-default values require equal effective minimum and maximum fraction digits and cannot be combined with significant-digit rounding or a non-`'auto'` `roundingPriority`. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` | +| `trailingZeroDisplay` | Whether to display trailing zeros. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` | + +When `notation: 'compact'` is set without any fraction- or significant-digit option, the effective digit defaults are `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1`, and `maximumSignificantDigits: 2`. In that case, `roundingPriority` defaults to `'morePrecision'` and `useGrouping` defaults to `'min2'`. ## Returns [#returns] diff --git a/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time-from-date.mdx b/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time-from-date.mdx index 867ab6b4f..e1f14e3bd 100644 --- a/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time-from-date.mdx +++ b/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time-from-date.mdx @@ -58,7 +58,7 @@ The `Date` to format relative to `baseDate`. **Type** `{ locales?: string | string[] } & Omit & { baseDate?: Date }` · **Optional** · **Default** `{}` -Formatting configuration: +Formatting configuration. The table lists `baseDate`, `locales`, and common options exposed by the published Core types, with their effective Core defaults. See the [`Intl.RelativeTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for supplemental standard and runtime-specific details. | Property | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | @@ -68,6 +68,8 @@ Formatting configuration: | `style` | The length of the output. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | | `localeMatcher` | The locale matching algorithm to use. | `'best fit' \| 'lookup'` | Yes | `'best fit'` | +`baseDate` is a Core-only field and is not passed to `Intl.RelativeTimeFormat`. Core also changes the upstream `numeric` default from `'always'` to `'auto'`. + ## Returns [#returns] **Type** `string` diff --git a/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time.mdx b/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time.mdx index 85e5af267..1d33313b2 100644 --- a/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time.mdx +++ b/docs/en-US/platform/core/reference/utility-functions/formatting/format-relative-time.mdx @@ -57,13 +57,13 @@ The relative time value. Negative numbers represent the past, positive numbers t **Type** `Intl.RelativeTimeFormatUnit` · **Required** -The unit of time: `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, or `'year'`. +The unit of time. Singular and plural forms are accepted: `'second'`/`'seconds'`, `'minute'`/`'minutes'`, `'hour'`/`'hours'`, `'day'`/`'days'`, `'week'`/`'weeks'`, `'month'`/`'months'`, `'quarter'`/`'quarters'`, and `'year'`/`'years'`. ### `options` [#options] **Type** `{ locales?: string | string[] } & Omit` · **Optional** · **Default** `{}` -Formatting configuration: +Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. See the [`Intl.RelativeTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for supplemental standard and runtime-specific details. | Property | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | @@ -72,6 +72,8 @@ Formatting configuration: | `style` | The length of the output. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | | `localeMatcher` | The locale matching algorithm to use. | `'best fit' \| 'lookup'` | Yes | `'best fit'` | +Core changes the upstream `numeric` default from `'always'` to `'auto'`; the other standard defaults come from `Intl.RelativeTimeFormat`. + ## Returns [#returns] **Type** `string` diff --git a/docs/en-US/platform/openapi/reference/project/create-branch.mdx b/docs/en-US/platform/openapi/reference/project/create-branch.mdx index df5f5c4b0..4ad843a04 100644 --- a/docs/en-US/platform/openapi/reference/project/create-branch.mdx +++ b/docs/en-US/platform/openapi/reference/project/create-branch.mdx @@ -21,7 +21,7 @@ Set up a branch before uploading files to it. To look up existing branches, use ## How it works [#how-it-works] - When `defaultBranch` is `true` and a default branch already exists, the existing default branch is returned. If the provided `branchName` differs, the default branch is renamed to match it. -- Creating a non-default branch requires a paid plan. On the free plan, a non-default branch request returns `403`. +- Creating a non-default branch requires the Starter plan. Without Starter, a non-default branch request returns `403`. - Otherwise the branch is created (or reused if it already exists) and returned as its `id` and `name`. ## Request [#request] diff --git a/docs/en-US/react/guides/configuring.mdx b/docs/en-US/react/guides/configuring.mdx index ac08d662c..749aac240 100644 --- a/docs/en-US/react/guides/configuring.mdx +++ b/docs/en-US/react/guides/configuring.mdx @@ -12,7 +12,7 @@ related: Server-rendered React and each framework integration need configuration plus a [`GTProvider`](/docs/react/reference/components/gt-provider) that exposes translations to your components. React SPAs initialize directly with [`initializeGTSPA`](/docs/react/reference/config#initialize-spa); follow the [React SPA Quickstart](/docs/react/react-spa-quickstart) for that setup. -*Note: `gt-react`, `gt-tanstack-start`, and `gt-react-native` do not read `gt.config.json` automatically — import it and pass its fields into the initialization call. In Next.js, the `withGTConfig` plugin reads `gt.config.json` for you.* +*Note: `gt-react`, `gt-tanstack-start`, and `gt-react-native` do not read `gt.config.json` automatically — import it and pass its fields into the initialization call. In Next.js, the [`withGTConfig`](/docs/react/nextjs/config) plugin reads `gt.config.json` for you.* ## Initialize the library [#initialize] @@ -36,7 +36,7 @@ Configure General Translation once, before your first render. - Next.js has no manual initialization call. Add the `withGTConfig` plugin to `next.config.ts`; it reads `gt.config.json` and wires up translation at build and request time. + Next.js has no manual initialization call. Add the [`withGTConfig`](/docs/react/nextjs/config) plugin to `next.config.ts`; it reads `gt.config.json` and wires up translation at build and request time. ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; @@ -62,7 +62,7 @@ Configure General Translation once, before your first render. initializeGT({ ...gtConfig, loadTranslations }); ``` - Register [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), then use [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) from `gt-tanstack-start` inside the request scope. With `localeRouting` enabled, middleware resolves the locale from the path prefix before the cookie and `Accept-Language` header. + Register [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), then use [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) from `gt-tanstack-start` inside the request scope. With [`localeRouting`](/docs/react/reference/config#locale-routing) enabled, middleware resolves the locale from the path prefix before the cookie and `Accept-Language` header. @@ -82,7 +82,7 @@ Configure General Translation once, before your first render. ## Add the provider [#provider] -Wrap your app in [`GTProvider`](/docs/react/reference/components/gt-provider) so components can read translations. +Wrap your app in [`GTProvider`](/docs/react/reference/components/gt-provider#contracts) so components can read translations. @@ -108,11 +108,11 @@ Wrap your app in [`GTProvider`](/docs/react/reference/components/gt-provider) so } ``` - The provider also accepts `region` and `enableI18n` (default `true`). When `enableI18n` is `false` or the active locale equals the default locale, content renders in the source language. + The provider also accepts [`region`](/docs/react/reference/components/gt-provider#region) and [`enableI18n`](/docs/react/reference/components/gt-provider#enable-i18n) (default `true`). When translation is disabled or the active locale equals the default locale, content renders in the source language. - Wrap your root layout in [``](/docs/react/reference/components/gt-provider). It reads the request locale and translations from the plugin, so it needs no `locale` or `translations` props. + Wrap your root layout in [``](/docs/react/reference/components/gt-provider#contracts). It reads the request locale and translations from the plugin, so the App Router provider accepts only `children`. ```tsx title="app/layout.tsx" import { GTProvider, useLocale } from 'gt-next'; @@ -131,7 +131,7 @@ Wrap your app in [`GTProvider`](/docs/react/reference/components/gt-provider) so - Pass the active `locale` and the `translations` for it. Both are required. + Pass the active [`locale`](/docs/react/reference/components/gt-provider#locale) and the [`translations`](/docs/react/reference/components/gt-provider#translations) for it. Both are required. ```tsx import { GTProvider, getTranslationsSnapshot } from 'gt-tanstack-start'; @@ -145,12 +145,12 @@ Wrap your app in [`GTProvider`](/docs/react/reference/components/gt-provider) so - Wrap your app in [``](/docs/react/reference/components/gt-provider). It loads translations for the active locale itself, so `translations` is not required; `locale` is optional and defaults to the device locale. + Wrap your app in [``](/docs/react/reference/components/gt-provider#contracts). It loads translations for the active locale itself, so it does not accept a `translations` prop; [`locale`](/docs/react/reference/components/gt-provider#locale) is optional and defaults to the stored or device locale. ```tsx import { GTProvider } from 'gt-react-native'; - + ; ``` @@ -158,7 +158,7 @@ Wrap your app in [`GTProvider`](/docs/react/reference/components/gt-provider) so - **Changed in v11 (React):** the `gt-react` provider no longer takes `config`, [`loadTranslations`](/docs/react/reference/functions/load-translations), or credentials as props. That setup now lives on the initialization call; the provider only receives the resolved `locale` and `translations`. + **Changed in v11 (React):** the `gt-react` provider no longer takes `config`, [`loadTranslations`](/docs/react/reference/functions/load-translations), or credentials as props. That setup now lives on the initialization call; the provider only receives the resolved [`locale`](/docs/react/reference/components/gt-provider#locale) and [`translations`](/docs/react/reference/components/gt-provider#translations). See the [Configuration reference](/docs/react/reference/config) for all provider and initialization options. @@ -207,7 +207,7 @@ Translation delivery and development features use a Project ID and API key, set General Translation resolves translations in one of these modes, based on your configuration. This is the same across frameworks: - **Local files:** provide [`loadTranslations`](/docs/react/reference/functions/load-translations) to import bundled JSON. See [Storing translations locally](/docs/react/guides/storing-translations). -- **General Translation CDN:** provide a `projectId` (without a custom loader) to fetch translations from GT's CDN at runtime. -- **Custom endpoint:** set a custom `cacheUrl` to load from your own host. +- **General Translation CDN:** provide a [`projectId`](/docs/react/reference/config#project-id) (without a custom loader) to fetch translations from GT's CDN at runtime. +- **Custom endpoint:** set a custom [`cacheUrl`](/docs/react/reference/config#cache-url) to load from your own host. -In development, providing a `projectId` and development API key enables on-demand translation and hot reload, so new strings translate as you work. In production, translations come from your pre-generated files or the CDN. +In development, providing a [`projectId`](/docs/react/reference/config#project-id) and development API key enables on-demand translation and hot reload, so new strings translate as you work. In production, translations come from your pre-generated files or the CDN. diff --git a/docs/en-US/react/guides/formatting-variables.mdx b/docs/en-US/react/guides/formatting-variables.mdx index 92b86396f..6653faf3b 100644 --- a/docs/en-US/react/guides/formatting-variables.mdx +++ b/docs/en-US/react/guides/formatting-variables.mdx @@ -1,7 +1,7 @@ --- title: Formatting numbers and dates -description: How to insert locale-aware numbers, currencies, dates, and variables into General Translation content. +description: How to format numbers, currency, dates, relative time, and dynamic values for each locale in React. related: links: - /docs/react/guides/handling-plurals-and-branches @@ -11,11 +11,23 @@ related: --- -Dynamic values inside translated content need to be marked so they are not sent for translation, and formatted values need to respect the reader's locale. General Translation provides variable components for both. These components come from the same core across every framework — only the import package differs. +Different locales have different conventions for formatting variables such as numbers, dates, times, and currency. + +Use the matching component for values that should adapt to the active locale, and use [``](/docs/react/reference/components/var) for dynamic values that should render unchanged. + +## Choose the right component [#choose] + +- [``](/docs/react/reference/components/var) renders a dynamic value without translating or formatting it. +- [``](/docs/react/reference/components/num) formats numbers, percentages, and units for the active locale. +- [``](/docs/react/reference/components/currency) formats an amount and currency code without converting its value. +- [``](/docs/react/reference/components/datetime) formats an absolute date, time, or both for the active locale. +- [``](/docs/react/reference/components/relative-time) formats relative wording such as "yesterday" or "in 3 days." + +These components share the same behavior across React, Next.js, TanStack Start, and React Native. Import them from your framework's package. ## Insert a raw value with `` [#var] -Use [``](/docs/react/reference/components/var) for dynamic content that should render as-is, such as a user name. It marks the value as a variable so the surrounding text stays translatable. +Use [``](/docs/react/reference/components/var) for dynamic content that should render exactly as provided: such as a username, email address, or identifier. Inside [``](/docs/react/reference/components/t), it keeps the value out of the translation while allowing the surrounding sentence to remain translatable. @@ -61,26 +73,91 @@ Use [``](/docs/react/reference/components/var) for dynamic content that sho ## Format numbers and currency [#numbers] -Use [``](/docs/react/reference/components/num) and [``](/docs/react/reference/components/currency) for locale-aware number and money formatting. Both accept `Intl` options, and both are imported from your framework's package alongside [``](/docs/react/reference/components/t). +Use [``](/docs/react/reference/components/num) and [``](/docs/react/reference/components/currency) for locale-aware number and money formatting. Import both from your framework's package alongside [``](/docs/react/reference/components/t). + +### Format a number + +Use [``](/docs/react/reference/components/num) for decimal grouping, percentages, and units. Pass [`options`](/docs/react/reference/components/num#options) to customize the output. + +```tsx + +

+ {count} downloads are complete. +

+; +``` + +```tsx + + {completionRate} + +``` + +### Format currency + +Use [``](/docs/react/reference/components/currency) with an ISO 4217 [`currency`](/docs/react/reference/components/currency#currency) code such as `USD` or `EUR`. ```tsx -

You have {count} items totaling {total}.

+

+ Your total is {total}. +

; ``` -[``](/docs/react/reference/components/currency) defaults to `USD`; pass `currency` for another code. It formats the value for the locale but does not convert between currencies. +[``](/docs/react/reference/components/currency) defaults to `USD`, but passing [`currency`](/docs/react/reference/components/currency#currency) makes the intended unit explicit. It localizes the symbol, grouping, and decimal display; it does not convert exchange rates. + +Pass [`options`](/docs/react/reference/components/currency#options) to control details such as currency display, rounding, and notation. ## Format dates and times [#dates] -Use [``](/docs/react/reference/components/datetime) for absolute dates and times, and [``](/docs/react/reference/components/relative-time) for relative values such as "3 days ago". Both accept `Intl` formatting options and an optional `locales` override. +Use [``](/docs/react/reference/components/datetime) for absolute dates and times, and [``](/docs/react/reference/components/relative-time) for relative values such as "3 days ago." + +### Format an absolute date or time + +Use [``](/docs/react/reference/components/datetime) for calendar dates and clock times. Pass [`options`](/docs/react/reference/components/datetime#options) to control the date style, time style, and time zone. ```tsx -

Published {publishedAt} ({publishedAt}).

+

+ Published{' '} + + {publishedAt} + + . +

; ``` -[``](/docs/react/reference/components/relative-time) can also take an explicit `value` and `unit` (for example `value={-3}` with `unit="day"`) instead of a date. +### Format relative time + +Use [``](/docs/react/reference/components/relative-time) with a `Date` to select an appropriate unit automatically: + +```tsx + +

+ Published {publishedAt}. +

+; +``` + +For a known offset, pass [`value`](/docs/react/reference/components/relative-time#value) and [`unit`](/docs/react/reference/components/relative-time#unit) instead: + +```tsx + +``` + +Pass [`options`](/docs/react/reference/components/relative-time#options) to choose numeric or natural wording and a long, short, or narrow style. + +To override the active locale, choose the component you are formatting: -See the [Components reference](/docs/react/reference/components/num) for every prop these components accept. +- [`` `locales`](/docs/react/reference/components/num#locales) +- [`` `locales`](/docs/react/reference/components/currency#locales) +- [`` `locales`](/docs/react/reference/components/datetime#locales) +- [`` `locales`](/docs/react/reference/components/relative-time#locales) diff --git a/docs/en-US/react/guides/handling-plurals-and-branches.mdx b/docs/en-US/react/guides/handling-plurals-and-branches.mdx index 9e1666ff6..82e99ccd8 100644 --- a/docs/en-US/react/guides/handling-plurals-and-branches.mdx +++ b/docs/en-US/react/guides/handling-plurals-and-branches.mdx @@ -1,7 +1,7 @@ --- title: Handling plurals and branches -description: How to render count-based and conditional content with the General Translation and components. +description: How to handle React pluralization and conditional translated content with and . related: links: - /docs/react/guides/formatting-variables @@ -11,11 +11,22 @@ related: --- -Text that changes with a count or a condition cannot be a single static string, because other languages pluralize and vary differently. Use [``](/docs/react/reference/components/plural) for counts and [``](/docs/react/reference/components/branch) for other conditions so every variation is translated correctly. Both components work the same in every framework; only the import package differs. +Different locales use different plural forms: English usually has `one` and `other`, while some languages need additional forms. + +Use [``](/docs/react/reference/components/plural) for count-based wording, and use [``](/docs/react/reference/components/branch) for other conditional content. + +## Choose plurals or branches [#choose] + +- Use [``](/docs/react/reference/components/plural) when a number determines the wording, such as message counts or search results. +- Use [``](/docs/react/reference/components/branch) when a status, plan, boolean, or other value determines the content. +- Place either component inside [``](/docs/react/reference/components/t) so every variation can be translated. +- Wrap dynamic values inside each variation with a [variable component](/docs/react/guides/formatting-variables), such as [``](/docs/react/reference/components/num) or [``](/docs/react/reference/components/var). + +Both components work the same across React, Next.js, TanStack Start, and React Native. Only the import package differs. ## Pluralize with `` [#plural] -Pass the count as `n` and provide a child for each plural form. General Translation picks the correct form for the active locale using the locale's plural rules. +Do not build plurals by checking `count === 1` or appending an `s`; that only models English grammar. Pass the count as [`n`](/docs/react/reference/components/plural#n), then provide the forms used by your source language. [``](/docs/react/reference/components/plural) selects the correct form with the active locale's [Unicode CLDR plural rules](https://cldr.unicode.org/index/cldr-spec/plural-rules). @@ -75,11 +86,21 @@ Pass the count as `n` and provide a child for each plural form. General Translat -Provide the plural categories your source language uses (commonly `one` and `other`); translators supply the categories each target language needs, such as `zero`, `two`, `few`, and `many`. +Provide the [`plural categories`](/docs/react/reference/components/plural#form) your source language uses—commonly `one` and `other` for English. Translators supply categories required by each target language, which may include `zero`, `two`, `few`, and `many`. + +If no category matches, [`children`](/docs/react/reference/components/plural#children) renders as the fallback: + +```tsx + + One result}> + {count} results + +; +``` ## Branch on a value with `` [#branch] -Use [``](/docs/react/reference/components/branch) to choose content based on an arbitrary value. Pass the value as `branch` and provide a child prop for each possible value, plus `children` as the fallback. Import [`Branch`](/docs/react/reference/components/branch) from the same package as [``](/docs/react/reference/components/t). +Use [``](/docs/react/reference/components/branch) when content depends on a value other than a count. Pass the value as [`branch`](/docs/react/reference/components/branch#branch), add a [prop for each expected value](/docs/react/reference/components/branch#value), and use [`children`](/docs/react/reference/components/branch#children) as the fallback. ```tsx @@ -93,6 +114,22 @@ Use [``](/docs/react/reference/components/branch) to choose content base ; ``` -Each branch child is translated independently, so every variation reads naturally in every language. +Each branch is translated independently, so translators can adapt its complete wording instead of working around an inline JavaScript conditional. + +### Replace conditionals inside `` + +An inline ternary makes the children of [``](/docs/react/reference/components/t) dynamic and prevents reliable extraction. Represent the same condition with [``](/docs/react/reference/components/branch): + +```tsx +// ❌ Inline conditional +{isActive ? 'Active' : 'Inactive'}; + +// ✅ Translatable branches + + + Inactive + +; +``` -*Note: The [``](/docs/react/reference/components/branch) component ignores any `data-*` attributes. The linter's [`no-data-attrs-on-branch`](/docs/react/reference/lint-rules) rule flags them.* +*Note: [``](/docs/react/reference/components/branch) ignores `data-*` attributes because non-reserved props represent branch values. Put test IDs and other data attributes on a wrapper element; the [`no-data-attrs-on-branch`](/docs/react/reference/lint-rules#no-data-attrs) lint rule flags this mistake.* diff --git a/docs/en-US/react/guides/linting-your-code.mdx b/docs/en-US/react/guides/linting-your-code.mdx index ccdf235af..0ca4da4ed 100644 --- a/docs/en-US/react/guides/linting-your-code.mdx +++ b/docs/en-US/react/guides/linting-your-code.mdx @@ -79,7 +79,7 @@ Add the plugin's `recommended` config to your flat ESLint config. It enables eve - The rules detect translation components and functions by their import source. `gt-tanstack-start` is not in the default list, so add it with the `libs` option on each rule. + The rules detect translation components and functions by their import source. `gt-tanstack-start` is not in the default list, so add it with the [`libs`](/docs/react/reference/lint-rules#libs) option on each rule. ```js title="eslint.config.js" import gtLint from '@generaltranslation/react-core-linter'; @@ -120,8 +120,8 @@ npx eslint . --fix The `recommended` config turns on three rules, all as errors: -- **`static-jsx`** — flags dynamic content inside [``](/docs/react/reference/components/t) and requires it to be wrapped in a variable component ([``](/docs/react/reference/components/var), [``](/docs/react/reference/components/num), [``](/docs/react/reference/components/currency), or [``](/docs/react/reference/components/datetime)). Auto-fixable. -- **`static-string`** — requires translation functions ([`useGT`](/docs/react/reference/hooks/use-gt), [`getGT`](/docs/node/reference/functions/get-gt), [`msg`](/docs/react/reference/functions/msg)) to receive static string literals, and steers dynamic values into ICU interpolation such as `gt('Hello, {name}!', { name })`. Auto-fixable. -- **`no-data-attrs-on-branch`** — flags `data-*` attributes on [``](/docs/react/reference/components/branch), which the component ignores. +- **[`static-jsx`](/docs/react/reference/lint-rules#static-jsx)** — flags dynamic content inside [``](/docs/react/reference/components/t) and requires it to be wrapped in a variable component ([``](/docs/react/reference/components/var), [``](/docs/react/reference/components/num), [``](/docs/react/reference/components/currency), or [``](/docs/react/reference/components/datetime)). Auto-fixable. +- **[`static-string`](/docs/react/reference/lint-rules#static-string)** — requires translation functions ([`useGT`](/docs/react/reference/hooks/use-gt), [`getGT`](/docs/node/reference/functions/get-gt), [`msg`](/docs/react/reference/functions/msg)) to receive static string literals, and steers dynamic values into ICU interpolation such as `gt('Hello, {name}!', { name })`. Auto-fixable. +- **[`no-data-attrs-on-branch`](/docs/react/reference/lint-rules#no-data-attrs)** — flags `data-*` attributes on [``](/docs/react/reference/components/branch), which the component ignores. See the [lint rules reference](/docs/react/reference/lint-rules) for each rule's options and examples. diff --git a/docs/en-US/react/guides/managing-locales.mdx b/docs/en-US/react/guides/managing-locales.mdx index ba096c1cc..ecea0c212 100644 --- a/docs/en-US/react/guides/managing-locales.mdx +++ b/docs/en-US/react/guides/managing-locales.mdx @@ -1,7 +1,7 @@ --- title: Managing locales -description: How to let users switch languages and read the active locale with General Translation. +description: How to configure supported locales, build a React language switcher, and read or change the active locale. related: links: - /docs/react/guides/translating-jsx @@ -11,11 +11,19 @@ related: --- -Your app declares which locales it supports, lets users choose one, and reads the active locale to render accordingly. This guide covers each part. +Locale codes such as `en-US` and `fr` connect a user's language choice to the correct translations and formatting rules. + +Declare the locales your app supports, let users choose one, and read the active locale when your UI needs language-specific behavior. + +## Understand locale state [#locale-state] + +- **Default locale:** the language your source content is written in and the final fallback when no supported locale matches. +- **Supported locales:** every locale a user can choose, including the default and target locales. +- **Active locale:** the supported locale selected from the URL, a saved preference, browser settings, or the default. ## Declare supported locales [#declare] -List your default and target locales in `gt.config.json`. These are the locales your app can switch between. +Set [`defaultLocale`](/docs/react/reference/config#default-locale) and list your target [`locales`](/docs/react/reference/config#locales) in `gt.config.json`: ```json title="gt.config.json" { @@ -24,11 +32,19 @@ List your default and target locales in `gt.config.json`. These are the locales } ``` -In React, TanStack Start, and React Native, pass these values into the initialization call. In Next.js, the `withGTConfig` plugin reads `gt.config.json` automatically, so there is no manual initialization. See [Configuring General Translation](/docs/react/guides/configuring) for each setup. +In React, TanStack Start, and React Native, pass these values into the initialization call. In Next.js, [`withGTConfig`](/docs/react/nextjs/config) reads `gt.config.json` automatically. See [Configuring General Translation](/docs/react/guides/configuring) for each framework's setup. ## Add a language switcher [#switcher] -Drop in [``](/docs/react/reference/components/locale-selector) for a ready-made dropdown of your supported locales. It changes the active locale when the user picks one. +Choose the simplest approach that fits your interface: + +- Use [``](/docs/react/reference/components/locale-selector) for a ready-made dropdown in React, Next.js, or TanStack Start. +- Use [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) to build a custom language switcher in any supported framework. +- Use [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) for a button or another control that changes to a known locale. + +### Use the ready-made selector + +Render [``](/docs/react/reference/components/locale-selector) in a client component. With no props, it lists every configured locale and changes the active locale when the user selects one. @@ -56,41 +72,146 @@ Drop in [``](/docs/react/reference/components/locale-selector) f - *Note: React Native does not ship a prebuilt [``](/docs/react/reference/components/locale-selector) component. Build your own with [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) (or [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) and [`useLocales`](/docs/react/reference/hooks/use-locales)), as shown below.* + *Note: React Native does not export [``](/docs/react/reference/components/locale-selector). Build a custom switcher with [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector), as shown below.* -To build your own switcher, use [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) to change the locale and [`useLocales`](/docs/react/reference/hooks/use-locales) to list the options. These hooks are available in every framework; import them from your framework's package. +### Build a custom language switcher + +[`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) provides the active locale, available locales, a setter, and localized display names in one hook. Use controls from your framework: + + + + ```tsx + import { useLocaleSelector } from 'gt-react'; + + function Switcher() { + const { locale, locales, setLocale, getLocaleProperties } = + useLocaleSelector(); + + return ( + + ); + } + ``` + + + + ```tsx + 'use client'; + + import { useLocaleSelector } from 'gt-next'; + + function Switcher() { + const { locale, locales, setLocale, getLocaleProperties } = + useLocaleSelector(); + + return ( + + ); + } + ``` + + + + ```tsx + import { useLocaleSelector } from 'gt-tanstack-start'; + + function Switcher() { + const { locale, locales, setLocale, getLocaleProperties } = + useLocaleSelector(); + + return ( + + ); + } + ``` + + + + ```tsx + import { Button, View } from 'react-native'; + import { useLocaleSelector } from 'gt-react-native'; + + function Switcher() { + const { locale, locales, setLocale, getLocaleProperties } = + useLocaleSelector(); + + return ( + + {locales.map((localeCode) => ( + ; } ``` -*Note: Changing the locale persists the choice — a cookie on the web (React, Next.js, TanStack Start) or the native store on React Native — and reloads so the new translations render. In TanStack Start with `localeRouting` enabled, it reloads at the corresponding locale pathname.* +## Persist and route locale choices [#persistence] + +Changing the locale through [``](/docs/react/reference/components/locale-selector), [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector), or [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) persists the choice and applies the new translations differently by framework: + +- **React:** stores the locale in a cookie, then reloads the page by default. A custom provider reload callback can replace the full-page reload. +- **Next.js App Router:** stores the locale in a cookie, then refreshes the server component tree. Locale middleware applies any configured path routing. +- **Next.js Pages Router:** stores the locale in a cookie. Configure the provider reload callback to navigate with the Pages Router and fetch the selected locale's page props. +- **TanStack Start:** stores the locale in a cookie, then reloads the page. With [`localeRouting`](/docs/react/reference/config#locale-routing) enabled, it navigates to the corresponding locale pathname. +- **React Native:** stores the locale in native storage (or `localStorage` on React Native Web), updates provider state, loads the locale's translations, and rerenders without browser navigation. + +For public pages, locale-based URLs make each language version shareable and indexable. Configure routing in the framework-specific guide: + +- [Next.js App Router middleware](/docs/react/nextjs/app-router-middleware) +- [Next.js Pages Router locale routing](/docs/react/nextjs/pages-router-middleware) +- [TanStack Start locale routing](/docs/react/tanstack-start/setup#locale-routing) ## Read the active locale [#read] -Use hooks to read locale state in your components: +Use locale hooks when rendering language-specific UI: - [`useLocale`](/docs/react/reference/hooks/use-locale) returns the active locale code. - [`useDefaultLocale`](/docs/react/reference/hooks/use-default-locale) returns the source locale. -- [`useLocaleDirection`](/docs/react/reference/hooks/use-locale-direction) returns `'ltr'` or `'rtl'`, for laying out the page. -- [`useLocaleProperties`](/docs/react/reference/hooks/use-locale-properties) returns display metadata for a locale, such as its name. +- [`useLocales`](/docs/react/reference/hooks/use-locales) returns every supported locale code. +- [`useLocaleDirection`](/docs/react/reference/hooks/use-locale-direction) returns `'ltr'` or `'rtl'` for page layout. +- [`useLocaleProperties`](/docs/react/reference/hooks/use-locale-properties) returns a locale's name, native name, region, script, and other display metadata. *Note: `gt-tanstack-start` does not currently export [`useLocaleDirection`](/docs/react/reference/hooks/use-locale-direction) or [`useLocaleProperties`](/docs/react/reference/hooks/use-locale-properties). Read locale metadata with [`getLocaleProperties`](/docs/platform/core/reference/utility-functions/locales/get-locale-properties) from `generaltranslation` instead.* -These hooks work in synchronous App Router server components. In async App Router components, use [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) and [`getLocaleDirection`](/docs/react/nextjs/reference/functions/get-locale-direction) from `gt-next/server` instead: +In Next.js, these hooks work in synchronous App Router server components. In async components, call [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) and [`getLocaleDirection`](/docs/react/nextjs/reference/functions/get-locale-direction) from `gt-next/server`: ```tsx import { getLocale, getLocaleDirection } from 'gt-next/server'; @@ -102,6 +223,4 @@ async function Layout() { } ``` -*Note: In Next.js, request-time locale detection and persistence run in middleware, covered in the Next.js framework pages.* - -See the [Hooks reference](/docs/react/reference/hooks/use-locale) for the full list. +See the [`useLocale`](/docs/react/reference/hooks/use-locale) Reference page for locale matching and fallback behavior. diff --git a/docs/en-US/react/guides/storing-translations.mdx b/docs/en-US/react/guides/storing-translations.mdx index c6cfc24ca..62e70c5d2 100644 --- a/docs/en-US/react/guides/storing-translations.mdx +++ b/docs/en-US/react/guides/storing-translations.mdx @@ -55,7 +55,7 @@ Provide a [`loadTranslations`](/docs/react/reference/functions/load-translations - Create a `loadTranslations.ts` file at your project root. The `withGTConfig` plugin auto-detects it (or set `loadTranslationsPath` explicitly). + Create a `loadTranslations.ts` file at your project root. The [`withGTConfig`](/docs/react/nextjs/config) plugin auto-detects it, or you can set [`loadTranslationsPath`](/docs/react/nextjs/config#load-translations-path) explicitly. ```ts title="loadTranslations.ts" export default async function loadTranslations(locale: string) { @@ -100,4 +100,4 @@ Provide a [`loadTranslations`](/docs/react/reference/functions/load-translations -With a local loader in place, translations are read from your bundle and no CDN request is made. To switch back to CDN delivery, remove the loader and provide a `projectId` instead (see [Configure General Translation](/docs/react/guides/configuring#delivery)). +With a local loader in place, translations are read from your bundle and no CDN request is made. To switch back to CDN delivery, remove the loader and provide a [`projectId`](/docs/react/reference/config#project-id) instead (see [Configure General Translation](/docs/react/guides/configuring#delivery)). diff --git a/docs/en-US/react/guides/translating-jsx.mdx b/docs/en-US/react/guides/translating-jsx.mdx index c46d4297f..98729f5f5 100644 --- a/docs/en-US/react/guides/translating-jsx.mdx +++ b/docs/en-US/react/guides/translating-jsx.mdx @@ -73,7 +73,7 @@ You do not assign a key or id — General Translation identifies the entry from ## Disambiguate with context [#context] -When the same text can translate differently depending on meaning, add `$context` so translators and the engine can tell entries apart. This works the same in every framework. +When the same text can translate differently depending on meaning, add [`$context`](/docs/react/reference/components/t#context) so translators and the engine can tell entries apart. This works the same in every framework. ```tsx @@ -83,7 +83,7 @@ When the same text can translate differently depending on meaning, add `$context ## Keep entries stable with an id [#id] -Pass `$id` to give an entry a stable identifier that does not change when you edit surrounding markup. This is optional; use it when you want a fixed reference for an entry. +Pass [`$id`](/docs/react/reference/components/t#id) to give an entry a stable identifier that does not change when you edit surrounding markup. This is optional; use it when you want a fixed reference for an entry. ```tsx diff --git a/docs/en-US/react/guides/translating-strings.mdx b/docs/en-US/react/guides/translating-strings.mdx index 588e95771..51f73d375 100644 --- a/docs/en-US/react/guides/translating-strings.mdx +++ b/docs/en-US/react/guides/translating-strings.mdx @@ -85,7 +85,7 @@ gt('Welcome back, {name}!', { name: user.name }); ## Add context [#context] -Pass `$context` to disambiguate a string, and `$id` to give it a stable identifier. +Pass [`$context`](/docs/react/reference/types/inline-translation-options#context) to disambiguate a string, and [`$id`](/docs/react/reference/types/inline-translation-options#id) to give it a stable identifier. ```tsx gt('Bank', { $context: 'a bank of a river' }); diff --git a/docs/en-US/react/guides/translating-with-dictionaries.mdx b/docs/en-US/react/guides/translating-with-dictionaries.mdx index 56c3536aa..70883ed9d 100644 --- a/docs/en-US/react/guides/translating-with-dictionaries.mdx +++ b/docs/en-US/react/guides/translating-with-dictionaries.mdx @@ -19,7 +19,7 @@ How you register your per-locale dictionaries depends on the framework. - Pass your dictionaries to [`GTProvider`](/docs/react/reference/components/gt-provider) through the `dictionaries` prop, alongside the required `locale` and `translations`. + Pass your dictionaries to [`GTProvider`](/docs/react/reference/components/gt-provider) through the [`dictionaries`](/docs/react/reference/components/gt-provider#dictionaries) prop, alongside the required [`locale`](/docs/react/reference/components/gt-provider#locale) and [`translations`](/docs/react/reference/components/gt-provider#translations). ```tsx @@ -29,7 +29,7 @@ How you register your per-locale dictionaries depends on the framework. - In Next.js you do not pass dictionaries to [`GTProvider`](/docs/react/reference/components/gt-provider). Create a dictionary file at your project root and register it with the config plugin, or let it be auto-detected. + In Next.js you do not pass [`dictionaries`](/docs/react/reference/components/gt-provider#dictionaries) to [`GTProvider`](/docs/react/reference/components/gt-provider). Create a dictionary file at your project root and register it with the config plugin, or let it be auto-detected. ```json title="dictionary.json" { @@ -45,7 +45,7 @@ How you register your per-locale dictionaries depends on the framework. - Pass your dictionaries to [`GTProvider`](/docs/react/reference/components/gt-provider) through the `dictionaries` prop, alongside the required `locale` and `translations`. + Pass your dictionaries to [`GTProvider`](/docs/react/reference/components/gt-provider) through the [`dictionaries`](/docs/react/reference/components/gt-provider#dictionaries) prop, alongside the required [`locale`](/docs/react/reference/components/gt-provider#locale) and [`translations`](/docs/react/reference/components/gt-provider#translations). ```tsx @@ -55,7 +55,7 @@ How you register your per-locale dictionaries depends on the framework. - Pass your dictionaries to [`GTProvider`](/docs/react/reference/components/gt-provider) through the `dictionaries` prop, alongside the active `locale`. + Pass your dictionaries to [`GTProvider`](/docs/react/reference/components/gt-provider) through the [`dictionaries`](/docs/react/reference/components/gt-provider#dictionaries) prop, alongside the active [`locale`](/docs/react/reference/components/gt-provider#locale). ```tsx @@ -138,7 +138,7 @@ Call [`useTranslations`](/docs/react/reference/hooks/use-translations) to get a -Pass a root id to scope all lookups under a prefix. This works the same in every framework (`getTranslations('home')` in Next.js and TanStack Start server code): +Pass [`rootId`](/docs/react/reference/hooks/use-translations#root-id) to scope all lookups under a prefix. This works the same in every framework (`getTranslations('home')` in Next.js and TanStack Start server code): ```tsx const t = useTranslations('home'); diff --git a/docs/en-US/react/reference/components/branch.mdx b/docs/en-US/react/reference/components/branch.mdx index bfe552521..ef85f0d13 100644 --- a/docs/en-US/react/reference/components/branch.mdx +++ b/docs/en-US/react/reference/components/branch.mdx @@ -7,7 +7,7 @@ description: Render content conditionally based on a value. API reference for th The `` component adds conditional logic to a translation. You pass a value to `branch`, and it renders the matching child prop. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -56,6 +56,8 @@ A prop per possible branch value. Each key corresponds to a value of `branch`, a ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="BranchExample.tsx" import { Branch } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/currency.mdx b/docs/en-US/react/reference/components/currency.mdx index cdb01058c..94a70fdb2 100644 --- a/docs/en-US/react/reference/components/currency.mdx +++ b/docs/en-US/react/reference/components/currency.mdx @@ -7,7 +7,7 @@ description: Format a currency amount for the active locale. API reference for t The `` component renders a numeric value formatted as a currency for the active locale. It only formats — it does not perform exchange-rate conversion. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -52,7 +52,40 @@ The ISO 4217 currency code, such as `USD` or `EUR`. It determines the symbol and **Type** `Intl.NumberFormatOptions` · **Optional** · **Default** `{}` -Formatting options following the [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) specification, such as `currencyDisplay` and fraction-digit limits. +The prop accepts [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options). Common options include: + +| Option | Description | Type | Optional | Default | +| --- | --- | --- | --- | --- | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` | +| `style` | Number-formatting style. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'currency'` | +| `currency` | ISO 4217 currency code. Overrides the top-level `currency` prop when provided here. | `string` | Yes | `currency` prop | +| `currencyDisplay` | How to display the currency. | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'` | Yes | `'symbol'` | +| `currencySign` | Standard or accounting notation for negative values. | `'standard' \| 'accounting'` | Yes | `'standard'` | +| `unit` | Unit identifier used if `style` is changed to `'unit'`. | `string` | Yes | — | +| `unitDisplay` | Width of the unit label. | `'long' \| 'short' \| 'narrow'` | Yes | `'short'` | +| `minimumIntegerDigits` | Minimum integer digits; shorter values are zero-padded. | `number` (`1`–`21`) | Yes | `1` | +| `minimumFractionDigits` | Minimum digits after the decimal separator. | `number` (`0`–`100`) | Yes | Currency-dependent | +| `maximumFractionDigits` | Maximum digits after the decimal separator. | `number` (`0`–`100`) | Yes | Currency-dependent | +| `minimumSignificantDigits` | Minimum significant digits. | `number` (`1`–`21`) | Yes | `1` | +| `maximumSignificantDigits` | Maximum significant digits. | `number` (`1`–`21`) | Yes | `21` | +| `roundingPriority` | Whether fraction or significant digits take priority. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'` | +| `roundingIncrement` | Increment used at the selected rounding magnitude. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` | +| `roundingMode` | Direction used when rounding. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` | +| `trailingZeroDisplay` | Whether to keep trailing zeros on whole numbers. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` | +| `notation` | Standard, scientific, engineering, or compact notation. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` | +| `compactDisplay` | Long or short labels for compact notation. | `'short' \| 'long'` | Yes | `'short'` | +| `useGrouping` | When to display grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact notation | +| `signDisplay` | When to display a positive or negative sign. | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'` | Yes | `'auto'` | + +The component applies `style: 'currency'`, the top-level `currency` prop, and `numberingSystem: 'latn'` before applying `options`. Values provided through `options` therefore override those defaults. + +- Currency fraction-digit defaults come from the currency's standard minor units. +- `compactDisplay` only applies when `notation` is `'compact'`. +- `roundingIncrement` cannot be combined with significant-digit rounding or a `roundingPriority` other than `'auto'`. +- Supported units, numbering systems, rounding fields, and option values depend on the JavaScript runtime. + +See the [`Intl.NumberFormat` options documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for the latest available options and runtime behavior. ### `locales` [#locales] @@ -68,6 +101,8 @@ An optional name for the currency field, used for metadata. ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="PriceDisplay.tsx" import { Currency } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/datetime.mdx b/docs/en-US/react/reference/components/datetime.mdx index 9c4dbdc55..b0da6220a 100644 --- a/docs/en-US/react/reference/components/datetime.mdx +++ b/docs/en-US/react/reference/components/datetime.mdx @@ -7,7 +7,7 @@ description: Format a date and time for the active locale. API reference for the The `` component displays a `Date` value as a localized date, time, or both. It supports custom formatting options and locale overrides. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -47,7 +47,37 @@ The date or time to format, as a `Date` object. **Type** `Intl.DateTimeFormatOptions` · **Optional** · **Default** `{}` -Formatting options following the [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) specification, such as `dateStyle`, `timeStyle`, and `timeZone`. +The prop accepts [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options). Common options include: + +| Option | Description | Type | Optional | Default | +| --- | --- | --- | --- | --- | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `calendar` | Calendar system, such as `gregory`, `chinese`, or `persian`. | `string` | Yes | `'gregory'` | +| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` | +| `hour12` | Whether to use a 12-hour clock. Overrides `hourCycle`. | `boolean` | Yes | Locale-dependent | +| `hourCycle` | Hour cycle used by the clock. | `'h11' \| 'h12' \| 'h23' \| 'h24'` | Yes | Locale-dependent | +| `timeZone` | IANA time zone or UTC offset. | `string` | Yes | Runtime time zone | +| `weekday` | Width of the weekday name. | `'long' \| 'short' \| 'narrow'` | Yes | — | +| `era` | Width of the era label. | `'long' \| 'short' \| 'narrow'` | Yes | — | +| `year` | Numeric or two-digit year. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | +| `month` | Numeric or named month format. | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes | `'numeric'` when no styles or components are set | +| `day` | Numeric or two-digit day. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | +| `dayPeriod` | Width of labels such as "in the morning" or "at night." | `'long' \| 'short' \| 'narrow'` | Yes | — | +| `hour` | Numeric or two-digit hour. | `'numeric' \| '2-digit'` | Yes | — | +| `minute` | Numeric or two-digit minute. | `'numeric' \| '2-digit'` | Yes | — | +| `second` | Numeric or two-digit second. | `'numeric' \| '2-digit'` | Yes | — | +| `fractionalSecondDigits` | Number of fractional-second digits. | `1 \| 2 \| 3` | Yes | — | +| `timeZoneName` | Width and style of the time-zone label. | `'long' \| 'short' \| 'shortOffset' \| 'longOffset' \| 'shortGeneric' \| 'longGeneric'` | Yes | — | +| `formatMatcher` | Algorithm for matching component options to a locale format. | `'basic' \| 'best fit'` | Yes | `'best fit'` | +| `dateStyle` | Preset date format. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | +| `timeStyle` | Preset time format. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | + +- `dateStyle` and `timeStyle` can be used together, but not with component options such as `weekday`, `year`, `month`, `day`, `hour`, `minute`, or `second`. +- `hour12` overrides `hourCycle`. +- `dayPeriod` only affects 12-hour clock formats. +- Supported calendars, numbering systems, time-zone labels, and option values depend on the JavaScript runtime. + +See the [`Intl.DateTimeFormat` options documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) for the latest available options and runtime behavior. ### `locales` [#locales] @@ -63,6 +93,8 @@ An optional name for the date field, used for metadata. ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="EventDate.tsx" import { DateTime } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/derive.mdx b/docs/en-US/react/reference/components/derive.mdx index 1e4532459..f900f5ee4 100644 --- a/docs/en-US/react/reference/components/derive.mdx +++ b/docs/en-US/react/reference/components/derive.mdx @@ -7,7 +7,7 @@ description: Mark finite content variants for extraction inside a translation. A The `` component handles sentence fragmentation and reusable content without sacrificing word agreement, conjugation, or word order. It tells the CLI to catalog every possible value of its children and create a separate translation entry for each. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -43,6 +43,8 @@ Static content — a literal, ternary, or function invocation with statically an ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="BasicExample.tsx" import { T, Derive } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/gt-provider.mdx b/docs/en-US/react/reference/components/gt-provider.mdx index cb85c9fae..7b6c3314d 100644 --- a/docs/en-US/react/reference/components/gt-provider.mdx +++ b/docs/en-US/react/reference/components/gt-provider.mdx @@ -1,125 +1,207 @@ --- title: "" -description: Provide the active locale and translations to the component tree. API reference for the component. +description: Provide translation and locale context to a React component tree. API reference for the component. --- -The `` component supplies the active locale and its translations to a server-rendered `gt-react` component tree. Use it when your server loads translations and passes them to the client. +The `` contract depends on the framework and router. Some providers receive locale data as props, while others resolve and load it for you. *Note: React SPAs initialized with [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) use the global translation cache and do not need a provider.* -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* - -*Note: how the locale and translations reach `` differs by framework. In `gt-react` you pass them as props (below); `gt-next`, `gt-tanstack-start`, and `gt-react-native` resolve them through their own setup, documented in each framework's section.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] -Wrap your app in `` after [initialization](/docs/react/reference/config#initialization). Pass the active `locale` and the `translations` for that locale, loaded with [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot). +| Runtime | Required props | Locale and translation source | +| --- | --- | --- | +| React server rendering | `locale`, `translations` | Your server loader | +| Next.js App Router | None | The request and `gt-next` cache | +| Next.js Pages Router | `locale`, `translations` | Pages Router data wrappers | +| TanStack Start | `locale`, `translations` | Your request loader | +| React Native | None | Native locale detection and the configured translation loader | + +The [Props](#props) section identifies exactly which provider variants accept each prop. + +## Framework contracts [#contracts] + + + + Server-rendered `gt-react` apps pass the active locale and a translation snapshot. Load the snapshot after [`initializeGT`](/docs/react/reference/config#initialize). + + ```tsx + import { GTProvider } from 'gt-react'; + + + + + ``` + + [`loadTranslations`](/docs/react/reference/functions/load-translations), [`loadDictionary`](/docs/react/reference/functions/load-dictionary), and credentials belong on the [initialization call](/docs/react/reference/config#initialization), not the provider. + + + **Changed in v11:** the `gt-react` `` no longer accepts `config`, [`loadTranslations`](/docs/react/reference/functions/load-translations), [`loadDictionary`](/docs/react/reference/functions/load-dictionary), or credentials. Move them to [`initializeGT`](/docs/react/reference/config#initialize), then pass the resolved `locale` and `translations` to the provider. + + + + + ### App Router + + The App Router provider is an async server component with only a `children` prop. It resolves the locale, region, translation state, translations, and dictionaries from the request and the `gt-next` cache. + + ```tsx title="app/layout.tsx" + import { GTProvider } from 'gt-next'; + + export default function RootLayout({ children }) { + return {children}; + } + ``` + + Do not pass `locale`, `translations`, `dictionaries`, `region`, or `enableI18n` to the App Router provider. + + ### Pages Router + + The Pages Router re-exports the shared `gt-react` provider. Pass the values injected through [server-side rendering](/docs/react/nextjs-pages-router-quickstart#quickstart) or [static generation](/docs/react/nextjs/pages-router-static-site-generation), and provide `_reload` when locale changes should use Next.js routing. + + ```tsx title="pages/_app.tsx" + import Router from 'next/router'; + import { GTProvider } from 'gt-next'; + + { + void Router.push(Router.pathname, Router.asPath, { locale }); + }} + > + + + ``` + + + + `gt-tanstack-start` re-exports the shared provider. Pass the active locale and its translation snapshot after registering [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware). + + ```tsx + import { GTProvider } from 'gt-tanstack-start'; -```tsx -import { GTProvider } from 'gt-react'; + + + + ``` + + + + The React Native provider detects the initial locale, loads its translations, and rerenders when the locale changes. `locale` is optional, and `translations` is not a public prop. - - - -``` + ```tsx + import { GTProvider } from 'gt-react-native'; -*Note: [`loadTranslations`](/docs/react/reference/functions/load-translations), [`loadDictionary`](/docs/react/reference/functions/load-dictionary), and credentials go on the [initialization call](/docs/react/reference/config#initialization), not on ``. The provider consumes the resolved locale and translations synchronously.* + + + + ``` - - **Changed in v11:** the `gt-react` `` no longer accepts `config`, [`loadTranslations`](/docs/react/reference/functions/load-translations), [`loadDictionary`](/docs/react/reference/functions/load-dictionary), or credentials. Move those to the [initialization call](/docs/react/reference/config#initialization) and pass the resolved `locale` and `translations` (from [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)) to the provider instead. - + Pass `fallback` to replace the built-in loading indicator while translations load. + + ## How it works [#how-it-works] -- **Synchronous translations.** The provider requires `translations` up front so translated content renders synchronously, without a loading flash. Produce this object with [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) after initialization. -- **Context for the tree.** In a provider-based setup, components below the provider read the active locale, translations, dictionaries, and region from it. -- **Toggling translation.** When `enableI18n` is `false`, the provider renders source-locale content and skips translation, which is useful for previewing the untranslated app. +- **React, TanStack Start, and Next.js Pages Router.** The provider receives a translation snapshot up front, so translated content renders synchronously. +- **Next.js App Router.** The server provider reads request state and loads translations and dictionaries before rendering its client boundary. +- **React Native.** The provider loads translations for the resolved locale through Suspense. It renders `fallback` until they are available. +- **Context for the tree.** Descendants read the active locale, translations, dictionaries, region, and translation state from provider context. +- **Locale changes.** Web providers persist the locale in a cookie and call their reload behavior. React Native persists it in native storage and updates provider state. ## Props [#props] | Prop | Description | Type | Optional | Default | | --- | --- | --- | --- | --- | -| [`locale`](#locale) | Active locale for the tree. | `string` | No | — | -| [`translations`](#translations) | Translations for the active locale. | `object` | No | — | -| [`dictionaries`](#dictionaries) | Per-locale dictionaries for [`useTranslations`](/docs/react/reference/hooks/use-translations). | `object` | Yes | — | -| [`region`](#region) | Active region code. | `string` | Yes | — | -| [`enableI18n`](#enable-i18n) | Translate content. When `false`, renders the source locale. | `boolean` | Yes | `true` | -| [`children`](#children) | The app tree. | `ReactNode` | Yes | — | +| [`children`](#children) | Component tree. Accepted by every provider. | `ReactNode` | Yes | — | +| [`locale`](#locale) | Active locale. Required by React, TanStack Start, and Next.js Pages Router; optional in React Native; not accepted in Next.js App Router. | `string \| LocaleCandidates` | Framework-specific | Device or stored locale in React Native | +| [`translations`](#translations) | Translation snapshot. Required by React, TanStack Start, and Next.js Pages Router; not accepted in Next.js App Router or React Native. | `object` | Framework-specific | — | +| [`dictionaries`](#dictionaries) | Per-locale dictionaries. Accepted by React, TanStack Start, Next.js Pages Router, and React Native; loaded internally in Next.js App Router. | `object` | Yes | — | +| [`region`](#region) | Active region. Accepted by React, TanStack Start, Next.js Pages Router, and React Native; resolved internally in Next.js App Router. | `string` | Yes | Stored region or `undefined` | +| [`enableI18n`](#enable-i18n) | Whether to translate. Accepted by React, TanStack Start, Next.js Pages Router, and React Native; resolved internally in Next.js App Router. | `boolean` | Yes | `true` | +| [`fallback`](#fallback) | Loading content while React Native fetches translations. React Native only. | `ReactNode` | Yes | Loading indicator | +| [`_reload`](#reload) | Framework reload callback. Accepted by React, TanStack Start, and Next.js Pages Router; not accepted by Next.js App Router or React Native. | `(state) => void` | Yes | Framework-specific | +| [`onMissingTranslation`](#missing-translation) | Handle a missing inline or JSX translation. Not accepted by Next.js App Router. | `OnMissingTranslation` | Yes | — | +| [`onMissingDictionaryEntry`](#missing-dictionary-entry) | Handle a missing dictionary entry. Not accepted by Next.js App Router. | `OnMissingDictionaryEntry` | Yes | — | +| [`onMissingDictionaryObj`](#missing-dictionary-object) | Handle a missing dictionary object. Not accepted by Next.js App Router. | `OnMissingDictionaryObj` | Yes | — | + +### `children` [#children] + +**Type** `ReactNode` · **Optional** + +The component tree that receives translation context. Every provider variant accepts `children`. ### `locale` [#locale] -**Type** `string` · **Required** +**Type** `string | LocaleCandidates` · **Framework-specific** + +The active locale for the tree: + +- Required as a resolved `string` in React, TanStack Start, and Next.js Pages Router. +- Optional in React Native, where it accepts locale candidates and defaults to the stored or device locale. +- Not accepted by the Next.js App Router provider, which resolves the request locale internally. -The active locale for the tree, as a BCP 47 code such as `es`. Read it downstream with [`useLocale`](/docs/react/reference/hooks/use-locale). +Read the result downstream with [`useLocale`](/docs/react/reference/hooks/use-locale). ### `translations` [#translations] -**Type** `object` · **Required** +**Type** `Record>` · **Framework-specific** -The translations for the active locale, in the shape the provider consumes synchronously. Produce it with [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) after initialization. +A translation snapshot produced by [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot). It is required in React, TanStack Start, and Next.js Pages Router so those providers can resolve content synchronously. + +The Next.js App Router provider loads the snapshot internally. The React Native provider accepts no `translations` prop and loads translations for the active locale itself. ### `dictionaries` [#dictionaries] -**Type** `object` · **Optional** +**Type** `Record` · **Optional** -Per-locale dictionaries used by [`useTranslations`](/docs/react/reference/hooks/use-translations) for id-based lookups. Omit this when you only use [``](/docs/react/reference/components/t) and [`useGT`](/docs/react/reference/hooks/use-gt). +Per-locale dictionaries used by [`useTranslations`](/docs/react/reference/hooks/use-translations) for id-based lookups. React, TanStack Start, Next.js Pages Router, and React Native accept this prop. The Next.js App Router provider loads dictionaries internally. ### `region` [#region] **Type** `string` · **Optional** -The active region code (for example, `US` or `GB`), used for region-specific formatting and by the region hooks and selectors. +The active region code, such as `US` or `GB`. React, TanStack Start, Next.js Pages Router, and React Native accept this prop. Next.js App Router resolves the region from the request. ### `enableI18n` [#enable-i18n] **Type** `boolean` · **Optional** · **Default** `true` -Whether to translate content. When `false`, the provider renders source-locale content and skips translation. +Whether to translate content. When `false`, the provider renders source-locale content. React, TanStack Start, Next.js Pages Router, and React Native accept this prop. Next.js App Router resolves the value from request state. -### `children` [#children] +### `fallback` [#fallback] **Type** `ReactNode` · **Optional** -Your application tree. In a provider-based setup, every component that translates or reads locale state must be a descendant of the provider. +React Native-only content shown while translations load. The default is a centered React Native `ActivityIndicator`. -## Examples [#examples] +### `_reload` [#reload] -```tsx title="src/routes/root.tsx" -import { - GTProvider, - initializeGT, - getTranslationsSnapshot, - parseLocale, -} from 'gt-react'; -import gtConfig from '../../gt.config.json'; +**Type** `(state: { locale: string; region: string | undefined; enableI18n: boolean }) => void` · **Optional** · **Default** Framework-specific -const loadTranslations = (locale: string) => - import(`../_gt/${locale}.json`).then((m) => m.default); +Callback after a web locale, region, or translation-state change. React and TanStack Start accept it through the shared provider. Next.js Pages Router uses it to replace a full-page reload with `Router.push`. -initializeGT({ ...gtConfig, loadTranslations }); +Plain `gt-react` and Next.js Pages Router fall back to `window.location.reload`. TanStack Start supplies pathname navigation when locale routing is enabled. The Next.js App Router provider supplies its own `router.refresh` callback and does not accept this prop. React Native updates provider state instead. -export async function loadRoot(request: Request) { - const locale = parseLocale(request); - return { - locale, - translations: await getTranslationsSnapshot(locale), - }; -} +### `onMissingTranslation` [#missing-translation] -export function Root({ locale, translations, children }) { - return ( - - {children} - - ); -} -``` - -```tsx -// Preview the untranslated (source-locale) app - - - -``` +**Type** `OnMissingTranslation` · **Optional** + +Advanced callback for a missing inline or JSX translation. Browser and React Native providers can use a supplied callback. Server-rendered providers install their own handler. + +### `onMissingDictionaryEntry` [#missing-dictionary-entry] + +**Type** `OnMissingDictionaryEntry` · **Optional** + +Advanced callback for a missing dictionary entry. Browser and React Native providers can use a supplied callback. Server-rendered providers install their own handler. + +### `onMissingDictionaryObj` [#missing-dictionary-object] + +**Type** `OnMissingDictionaryObj` · **Optional** + +Advanced callback for a missing dictionary object. Browser and React Native providers can use a supplied callback. Server-rendered providers install their own handler. diff --git a/docs/en-US/react/reference/components/locale-selector.mdx b/docs/en-US/react/reference/components/locale-selector.mdx index 65863ab4f..b51a6e2fe 100644 --- a/docs/en-US/react/reference/components/locale-selector.mdx +++ b/docs/en-US/react/reference/components/locale-selector.mdx @@ -7,7 +7,7 @@ description: Render a dropdown for switching the active locale. API reference fo The `` component is a prebuilt, client-side dropdown of your app's configured locales, so you can add a working language switcher without building your own. -*Available in `gt-react`, `gt-next`, and `gt-tanstack-start`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, and `gt-tanstack-start`.* *Note: not exported by `gt-react-native`. For a custom selector, use [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector).* @@ -15,6 +15,8 @@ The `` component is a prebuilt, client-side dropdown of your app Render `` anywhere in a client component. With no props, it lists the configured locales. +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx import { LocaleSelector } from 'gt-react'; @@ -28,7 +30,7 @@ export default function MyComponent() { ## How it works [#how-it-works] - **Reads context.** By default, the options come from the supported locales in the [``](/docs/react/reference/components/gt-provider) context. Provide `locales` to show a subset. -- **Switches the locale.** Selecting an option sets the active locale, which persists the choice and reloads the page. +- **Switches the locale.** Selecting an option persists the active locale and applies the framework's refresh, reload, or navigation behavior. See [Managing locales](/docs/react/guides/managing-locales#persistence). - **Renders nothing when empty.** The component returns `null` when no locales are available. ## Props [#props] diff --git a/docs/en-US/react/reference/components/num.mdx b/docs/en-US/react/reference/components/num.mdx index 1bf1fa0ee..ee5914e59 100644 --- a/docs/en-US/react/reference/components/num.mdx +++ b/docs/en-US/react/reference/components/num.mdx @@ -7,7 +7,7 @@ description: Format a number for the active locale. API reference for the The `` component applies locale-aware digit grouping and decimal formatting to a number. It is a variable component for use inside a [``](/docs/react/reference/components/t), or on its own. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -45,7 +45,38 @@ The number to format. Strings are parsed into numbers before formatting. **Type** `Intl.NumberFormatOptions` · **Optional** · **Default** `{}` -Formatting options following the [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) specification, such as `style`, `maximumFractionDigits`, and grouping. +The prop accepts [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options). Common options include: + +| Option | Description | Type | Optional | Default | +| --- | --- | --- | --- | --- | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | `'latn'` | +| `style` | Plain number, currency, percent, or unit formatting. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'decimal'` | +| `currency` | ISO 4217 currency code. Required when `style` is `'currency'`. | `string` | Yes | — | +| `currencyDisplay` | How to display a currency. | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'` | Yes | `'symbol'` | +| `currencySign` | Standard or accounting notation for negative currency values. | `'standard' \| 'accounting'` | Yes | `'standard'` | +| `unit` | Unit identifier, such as `kilometer` or `megabyte`. Required when `style` is `'unit'`. | `string` | Yes | — | +| `unitDisplay` | Width of the unit label. | `'long' \| 'short' \| 'narrow'` | Yes | `'short'` | +| `minimumIntegerDigits` | Minimum integer digits; shorter values are zero-padded. | `number` (`1`–`21`) | Yes | `1` | +| `minimumFractionDigits` | Minimum digits after the decimal separator. | `number` (`0`–`100`) | Yes | Style-dependent | +| `maximumFractionDigits` | Maximum digits after the decimal separator. | `number` (`0`–`100`) | Yes | Style-dependent | +| `minimumSignificantDigits` | Minimum significant digits. | `number` (`1`–`21`) | Yes | `1` | +| `maximumSignificantDigits` | Maximum significant digits. | `number` (`1`–`21`) | Yes | `21` | +| `roundingPriority` | Whether fraction or significant digits take priority. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'` | +| `roundingIncrement` | Increment used at the selected rounding magnitude. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` | +| `roundingMode` | Direction used when rounding. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` | +| `trailingZeroDisplay` | Whether to keep trailing zeros on whole numbers. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` | +| `notation` | Standard, scientific, engineering, or compact notation. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` | +| `compactDisplay` | Long or short labels for compact notation. | `'short' \| 'long'` | Yes | `'short'` | +| `useGrouping` | When to display grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact notation | +| `signDisplay` | When to display a positive or negative sign. | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'` | Yes | `'auto'` | + +- Fraction-digit defaults depend on `style` and, for currency, the currency's standard minor units. +- `compactDisplay` only applies when `notation` is `'compact'`. +- `roundingIncrement` cannot be combined with significant-digit rounding or a `roundingPriority` other than `'auto'`. +- Supported units, numbering systems, rounding fields, and option values depend on the JavaScript runtime. + +See the [`Intl.NumberFormat` options documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for the latest available options and runtime behavior. ### `locales` [#locales] @@ -61,6 +92,8 @@ An optional name for the number field, used for metadata. ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="QuantityDisplay.tsx" import { Num } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/plural.mdx b/docs/en-US/react/reference/components/plural.mdx index d802a39c4..434a560e6 100644 --- a/docs/en-US/react/reference/components/plural.mdx +++ b/docs/en-US/react/reference/components/plural.mdx @@ -7,7 +7,7 @@ description: Render count-based content using the active locale's plural rules. The `` component swaps its wording based on a count so the sentence agrees with the number in each language. English needs two ("one item" / "two items"), while other languages need up to six. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -73,6 +73,8 @@ A prop per plural category — `zero`, `one`, `two`, `few`, `many`, `other` (or ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="BasicExample.tsx" import { Plural } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/region-selector.mdx b/docs/en-US/react/reference/components/region-selector.mdx index f051d0382..55942212e 100644 --- a/docs/en-US/react/reference/components/region-selector.mdx +++ b/docs/en-US/react/reference/components/region-selector.mdx @@ -7,7 +7,7 @@ description: Render a dropdown for switching the active region. API reference fo The `` component gives users a prebuilt dropdown for selecting their region, without you building a custom selector. It is a client-side component that reads region data from the [``](/docs/react/reference/components/gt-provider) context. -*Available in `gt-react` and `gt-next`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react` and `gt-next`.* *Note: not exported by `gt-tanstack-start` or `gt-react-native`.* @@ -15,6 +15,8 @@ The `` component gives users a prebuilt dropdown for selecting t Render `` inside your provider. With no props, it infers regions from the supported locales. +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx import { RegionSelector } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/relative-time.mdx b/docs/en-US/react/reference/components/relative-time.mdx index 1f87223fc..7edfd0271 100644 --- a/docs/en-US/react/reference/components/relative-time.mdx +++ b/docs/en-US/react/reference/components/relative-time.mdx @@ -7,7 +7,7 @@ description: Format localized relative time, such as 2 hours ago. API reference The `` component renders relative-time wording with the unit and phrasing conventions of the active locale. It works either by auto-selecting the best unit from a `Date`, or from an explicit value and unit. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -75,7 +75,17 @@ The base date the relative time is measured against. Defaults to `new Date()` at **Type** `Intl.RelativeTimeFormatOptions` · **Optional** · **Default** `{ numeric: 'auto', style: 'long' }` -Formatting options following the [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) specification. +The prop uses [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options). `` currently reads these options: + +| Option | Description | Type | Optional | Default | +| --- | --- | --- | --- | --- | +| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | +| `style` | Width of the relative-time wording. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` | +| `numeric` | Whether to always use a number or allow wording such as "yesterday" and "tomorrow." | `'always' \| 'auto'` | Yes | `'auto'` | + +Other fields from the broader `Intl.RelativeTimeFormatOptions` TypeScript type are not forwarded by ``. + +See the [`Intl.RelativeTimeFormat` options documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for the latest standard options. Check the table above for the options currently supported by ``. ### `locales` [#locales] @@ -91,6 +101,8 @@ An optional name for the entry, used for metadata. ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="PostTimestamp.tsx" import { RelativeTime } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/t.mdx b/docs/en-US/react/reference/components/t.mdx index 4cd4b22af..20f83de79 100644 --- a/docs/en-US/react/reference/components/t.mdx +++ b/docs/en-US/react/reference/components/t.mdx @@ -7,7 +7,7 @@ description: Translate JSX children in place. API reference for the componen The `` component is the primary translation method in `gt-react`. It translates its JSX children — plain text and nested markup — into the active locale, in place. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -72,6 +72,8 @@ Marks the translated content as requiring approval before use, so it is held for ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="Greeting.tsx" import { T } from 'gt-react'; diff --git a/docs/en-US/react/reference/components/var.mdx b/docs/en-US/react/reference/components/var.mdx index 9241820e4..ddcb4201f 100644 --- a/docs/en-US/react/reference/components/var.mdx +++ b/docs/en-US/react/reference/components/var.mdx @@ -7,7 +7,7 @@ description: Render a dynamic value inside a translation without translating it. The `` component renders dynamic content that should not be translated. Use it for values, code snippets, or private information such as API keys or personal data, so the surrounding text stays translatable. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -47,6 +47,8 @@ An optional name for the variable, used for metadata and to identify the value i ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="Address.tsx" import { T, Var } from 'gt-react'; diff --git a/docs/en-US/react/reference/functions/declare-var.mdx b/docs/en-US/react/reference/functions/declare-var.mdx index d0c747ed7..7989e1096 100644 --- a/docs/en-US/react/reference/functions/declare-var.mdx +++ b/docs/en-US/react/reference/functions/declare-var.mdx @@ -7,7 +7,7 @@ description: Mark a non-translatable variable inside derived content. API refere The `declareVar` function marks dynamic content inside [`derive`](/docs/react/reference/functions/derive) content that should be excluded from translation and handled as a variable at runtime. It is the string equivalent of the [``](/docs/react/reference/components/var) component. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -67,6 +67,8 @@ A string containing ICU-compatible markers that preserves the original value and ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="BasicUsage.tsx" import { derive, declareVar, gt } from 'gt-react'; diff --git a/docs/en-US/react/reference/functions/decode-vars.mdx b/docs/en-US/react/reference/functions/decode-vars.mdx index c89e43ec8..9f29caf96 100644 --- a/docs/en-US/react/reference/functions/decode-vars.mdx +++ b/docs/en-US/react/reference/functions/decode-vars.mdx @@ -7,7 +7,7 @@ description: Expand variables encoded by declareVar back into their values. API The `decodeVars` function extracts the original values from strings that contain [`declareVar`](/docs/react/reference/functions/declare-var) markers. Because [`declareVar`](/docs/react/reference/functions/declare-var) adds ICU-compatible markers to source text, those markers can interfere with string-processing logic — `decodeVars` removes them. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -49,6 +49,8 @@ The string with ICU markers removed, containing the original variable values. ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="BasicUsage.tsx" import { declareVar, decodeVars } from 'gt-react'; diff --git a/docs/en-US/react/reference/functions/derive.mdx b/docs/en-US/react/reference/functions/derive.mdx index d56f9b3fa..c584da6bf 100644 --- a/docs/en-US/react/reference/functions/derive.mdx +++ b/docs/en-US/react/reference/functions/derive.mdx @@ -7,7 +7,7 @@ description: Mark finite content variants inside a string translation for extrac The `derive` function allows static function calls or variable expressions inside a string translation. It is the string equivalent of the [``](/docs/react/reference/components/derive) component, useful for reusable code, internationalizing fragmented sentences, and preserving word agreement. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -51,6 +51,8 @@ Returns `content` unchanged, preserving its type [`T`](/docs/react/reference/com ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="FragmentedSentence.tsx" import { derive, gt } from 'gt-react'; diff --git a/docs/en-US/react/reference/functions/get-translations-snapshot.mdx b/docs/en-US/react/reference/functions/get-translations-snapshot.mdx index 2deac7c3a..75ecb2bfb 100644 --- a/docs/en-US/react/reference/functions/get-translations-snapshot.mdx +++ b/docs/en-US/react/reference/functions/get-translations-snapshot.mdx @@ -7,7 +7,7 @@ description: Load a locale's translations for GTProvider. API reference for getT The `getTranslationsSnapshot` function loads the translations for a locale in the shape that [``](/docs/react/reference/components/gt-provider) expects for its `translations` prop. Call it after initialization to produce the snapshot the provider consumes synchronously. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -43,6 +43,8 @@ A promise resolving to the translations snapshot for the locale, in the shape [` ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx title="src/routes/root.tsx" import { GTProvider, diff --git a/docs/en-US/react/reference/functions/msg.mdx b/docs/en-US/react/reference/functions/msg.mdx index ca5baca6f..44e8b7f27 100644 --- a/docs/en-US/react/reference/functions/msg.mdx +++ b/docs/en-US/react/reference/functions/msg.mdx @@ -7,7 +7,7 @@ description: Register and encode a string for translation at module scope. API r The `msg` function marks and encodes a string for translation. Use it to register strings at module scope — outside a component — then resolve them at runtime with [`useMessages`](/docs/react/reference/hooks/use-messages). -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -26,6 +26,8 @@ const encodedString = msg('Hello, world!'); - **Decoding.** `decodeMsg` extracts the original interpolated string from an encoded message. [`decodeOptions`](/docs/node/reference/functions/decode-options) extracts the options. - **Arrays.** `msg` also accepts an array of strings; when an `$id` is provided, each entry is given a unique id of `${id}.${index}`. +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx import { msg, decodeMsg } from 'gt-react'; diff --git a/docs/en-US/react/reference/functions/t-function.mdx b/docs/en-US/react/reference/functions/t-function.mdx index 49dbf10c1..2813d85c8 100644 --- a/docs/en-US/react/reference/functions/t-function.mdx +++ b/docs/en-US/react/reference/functions/t-function.mdx @@ -7,7 +7,7 @@ description: Translate strings synchronously at module scope. API reference for The `t` function is a synchronous, module-level string translation function for client-side `gt-react` apps. Unlike [`useGT`](/docs/react/reference/hooks/use-gt) (which requires React context) or [`msg`](/docs/react/reference/functions/msg) (which encodes strings for later resolution), `t` returns the translated string directly and can be called anywhere in browser code, including outside React components. -*Available in `gt-react` and `gt-tanstack-start`. Examples import from `gt-react`; import from `gt-tanstack-start` for TanStack Start.* +*Available in `gt-react` and `gt-tanstack-start`.* *Note: not exported by `gt-next` or `gt-react-native`. In `gt-next`, use [`useGT`](/docs/react/reference/hooks/use-gt) in synchronous components or [`getGT`](/docs/react/nextjs/reference/functions/get-gt) in async App Router components.* @@ -15,6 +15,8 @@ The `t` function is a synchronous, module-level string translation function for Import `t` from `gt-react` and call it with a string. +*Examples import from `gt-react`; import from `gt-tanstack-start` for TanStack Start.* + ```tsx import { t } from 'gt-react'; diff --git a/docs/en-US/react/reference/hooks/use-default-locale.mdx b/docs/en-US/react/reference/hooks/use-default-locale.mdx index b5d5be5ac..7dcf4947e 100644 --- a/docs/en-US/react/reference/hooks/use-default-locale.mdx +++ b/docs/en-US/react/reference/hooks/use-default-locale.mdx @@ -7,12 +7,14 @@ description: Read the source (default) locale. API reference for useDefaultLocal The `useDefaultLocale` hook returns your app's fallback language, used when a user's preferred locale is unavailable. It reads this default (source) locale from the [``](/docs/react/reference/components/gt-provider) context. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] Call `useDefaultLocale` to read the source locale. +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx import { useDefaultLocale } from 'gt-react'; diff --git a/docs/en-US/react/reference/hooks/use-gt.mdx b/docs/en-US/react/reference/hooks/use-gt.mdx index 5518b3364..68337ce6e 100644 --- a/docs/en-US/react/reference/hooks/use-gt.mdx +++ b/docs/en-US/react/reference/hooks/use-gt.mdx @@ -7,7 +7,7 @@ description: Get a function to translate strings inline. API reference for useGT The `useGT` hook returns a function that translates strings into the active locale. Use it for labels, placeholders, and other standalone strings, where [``](/docs/react/reference/components/t) does not fit. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] @@ -44,6 +44,8 @@ A function that translates the provided string into the active locale. ## Examples [#examples] +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx import { useGT } from 'gt-react'; diff --git a/docs/en-US/react/reference/hooks/use-locale-direction.mdx b/docs/en-US/react/reference/hooks/use-locale-direction.mdx index f96843a41..789e83fca 100644 --- a/docs/en-US/react/reference/hooks/use-locale-direction.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-direction.mdx @@ -7,7 +7,7 @@ description: Read the text direction for a locale. API reference for useLocaleDi The `useLocaleDirection` hook tells you whether a locale is written left-to-right (`'ltr'`) or right-to-left (`'rtl'`), defaulting to the active locale when you do not pass one. -*Available in `gt-react`, `gt-next`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, and `gt-react-native`.* *Note: not exported by `gt-tanstack-start`.* @@ -15,6 +15,8 @@ The `useLocaleDirection` hook tells you whether a locale is written left-to-righ Call `useLocaleDirection` to get the direction, and apply it with the `dir` attribute. +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx import { useLocaleDirection } from 'gt-react'; diff --git a/docs/en-US/react/reference/hooks/use-locale-properties.mdx b/docs/en-US/react/reference/hooks/use-locale-properties.mdx index 565cbb44b..1a5c6e8fa 100644 --- a/docs/en-US/react/reference/hooks/use-locale-properties.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-properties.mdx @@ -7,7 +7,7 @@ description: Read display metadata for a locale. API reference for useLocaleProp The `useLocaleProperties` hook resolves a locale code into its human-readable details: name, native name, language, region, and script. -*Available in `gt-react`, `gt-next`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, and `gt-react-native`.* *Note: not exported by `gt-tanstack-start`.* @@ -15,6 +15,8 @@ The `useLocaleProperties` hook resolves a locale code into its human-readable de Call `useLocaleProperties` with a locale code to get its properties. +*Examples import from `gt-react`; import from your framework's package instead.* + ```tsx import { useLocale, useLocaleProperties } from 'gt-react'; diff --git a/docs/en-US/react/reference/hooks/use-locale-selector.mdx b/docs/en-US/react/reference/hooks/use-locale-selector.mdx index df30ef794..2e2f03467 100644 --- a/docs/en-US/react/reference/hooks/use-locale-selector.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-selector.mdx @@ -7,12 +7,14 @@ description: Build a custom locale switcher. API reference for useLocaleSelector The `useLocaleSelector` hook exposes the pieces for a custom language switcher: the active locale, the available locales, a locale-properties helper, and a setter to change the locale. -*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`. Examples import from `gt-react`; import from your framework's package instead.* +*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.* ## Overview [#overview] Call `useLocaleSelector` and wire its values into your own `