diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md index 4aa8f05d7..058f554ed 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. @@ -177,7 +178,7 @@ Use a bolded breadcrumb with `>`: **Project > Automations**, **Project > Context ### Product and term casing -Always capitalize these as product terms: **Dashboard**, **Locadex**, **Core**, **Google Drive**, **Project** (and **Projects**), **Context Group** (and **Context Groups**), **Glossary**, **Directive** (and **Directives**), and **Autoderive** (the CLI feature). Also capitalize the product scopes **Organization** and **Enterprise**, and **GitHub**. Lowercase "group" when they are not part of the proper term. +Always capitalize these as product terms: **Dashboard**, **Locadex**, **Core**, **Google Drive**, **Project** (and **Projects**), **Context Group** (and **Context Groups**), **Glossary**, **Custom Prompt** (and **Custom Prompts**), and **Autoderive** (the CLI feature). Also capitalize the product scopes **Organization** and **Enterprise**, and **GitHub**. Lowercase "group" when they are not part of the proper term. *Note: capitalize **Autoderive** only when referring to the feature in prose; the* `gt.config.json` *key stays lowercase in code as* `autoderive`*. Do not write "General Translation Autoderive" — the feature name stands on its own.* @@ -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 @@ -425,13 +426,15 @@ 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. +- `title`: **sentence case** — capitalize only the first word, except proper/product names (Dashboard, Locadex, Core, Organization, Project, Enterprise, Context Group, Glossary, Custom Prompts, 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: @@ -501,7 +504,7 @@ Only document capabilities that actually exist, and resolve anything uncertain a A "common workflow" section is a bulleted roundup that points readers to the main tasks or settings from a landing page (as in the Dashboard get-started **Key workflows** and **Configuration** lists). Each bullet starts with the action, then a short description, then a link: ```text -- **Define context and key terms for translation:** use Context Groups to guide terminology and style across Projects. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). +- **Define context and key terms for translation:** use Context Groups to guide terminology and style across Projects. See [Defining context for translations](/docs/platform/dashboard/guides/defining-context-for-translations). ``` Use common workflow sections on **Get Started pages and other overview/landing pages** to surface the primary tasks, instead of duplicating full how-tos inline. Do not use them mid-guide, where ordered steps belong. @@ -518,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 @@ -526,7 +531,7 @@ Anatomy: 1. Open your Organization in the Dashboard. 2. Go to the **Context** page. 3. Create a **Context Group**. -4. Add a **Glossary** (for terminology) and/or **Directives** (for style and tone). +4. Add a **Glossary** (for terminology) and/or **Custom Prompts** (for style and tone). 5. **Assign** your Context Group to relevant Project(s). 6. Generate translations or apply updates to existing translations. ``` @@ -556,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. @@ -806,7 +813,7 @@ CI validates every `meta.json`: entries must resolve, every navigable child must - Navigation separators use `>`, not `->`. - `.md` link suffix usage is consistent within the file. - Notes and tips use the established format for their page type and are consistent across sibling pages. -- Product/term casing matches the canonical list (Dashboard, Locadex, Core, Google Drive, Project, Context Group, Glossary, Directives, Organization, Enterprise, GitHub). +- Product/term casing matches the canonical list (Dashboard, Locadex, Core, Google Drive, Project, Context Group, Glossary, Custom Prompts, Organization, Enterprise, GitHub). - Reference descriptions end with a second sentence: `API reference for X.` for API/library pages, or `Reference for X.` for non-API reference pages (ending with a period). - No broken internal links (verify the target file exists). - `related.links` follow the page-type rule: quickstart/entry pages point to four of that section's guides (or all if the section has fewer than four); guide pages link **all** the section's other guides, trimming to the four most relevant only when there are more than four others; neither links reference pages or quickstarts (the guide-less OpenAPI section is the only exception). diff --git a/apps/content/package.json b/apps/content/package.json index f924f58c1..6ad724d5d 100644 --- a/apps/content/package.json +++ b/apps/content/package.json @@ -6,6 +6,7 @@ "scripts": { "build": "next build", "dev": "next dev", + "generate-openapi-docs": "node scripts/generate-openapi-docs.mjs", "postinstall": "fumadocs-mdx", "start": "next start" }, diff --git a/apps/content/scripts/generate-openapi-docs.mjs b/apps/content/scripts/generate-openapi-docs.mjs new file mode 100644 index 000000000..d2cb4cddc --- /dev/null +++ b/apps/content/scripts/generate-openapi-docs.mjs @@ -0,0 +1,185 @@ +#!/usr/bin/env node +/** + * OpenAPI Documentation Generator + * + * Generates one MDX page per API operation from the canonical OpenAPI spec + * (docs/en-US/platform/openapi/openapi.yaml). Each generated page renders with + * the `` component (registered in the docs MDX components) against + * the `gt-api` schema, which provides the interactive request playground. + * + * The generated pages live in `docs/en-US/platform/openapi/reference`. The + * section's `overview.mdx`, `openapi.yaml`, and all `meta.json` files (section + * + per-group ordering) are authored by hand and are NOT touched by this + * script — only Fumadocs-generated `.mdx` operation pages are regenerated. + * + * Every operation must have an entry in PAGES below. The mapping pins each + * operation to a stable URL slug so links from other docs pages never break + * when the spec is regenerated. + * + * Usage: + * pnpm run generate-openapi-docs + */ + +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +import { generateFiles } from 'fumadocs-openapi'; +import { createOpenAPI } from 'fumadocs-openapi/server'; + +const REPO_ROOT = path.join(fileURLToPath(import.meta.url), '../../../..'); +const OPENAPI_DIR = path.join(REPO_ROOT, 'docs/en-US/platform/openapi'); +const OUTPUT_DIR = path.join(OPENAPI_DIR, 'reference'); + +// Mirror src/lib/openapi.ts. We re-create the server here instead of importing +// that module because it lives behind a Next.js path alias and pulls in +// app-only code paths that aren't resolvable from a plain node script. +const openapi = createOpenAPI({ + input: () => ({ + 'gt-api': path.join(OPENAPI_DIR, 'openapi.yaml'), + }), + proxyUrl: '/api/proxy', +}); + +// Stable output slug (`/`) for every operation, keyed by +// ` `. Grouping intentionally differs from the spec's tags: +// branch, tag, and job operations fold into the `project` and `translation` +// sidebar groups. +const PAGES = { + 'post /v2/project/files/upload-files': 'files/upload-source', + 'post /v2/project/files/upload-translations': 'files/upload-translations', + 'post /v2/project/files/diffs': 'files/submit-diffs', + 'post /v2/project/files/download': 'files/download-many', + 'get /v2/project/files/download/{fileId}': 'files/download', + 'post /v2/project/files/publish': 'files/publish-files', + 'post /v2/project/files/info': 'files/file-info', + 'get /v2/project/translations/files/status/{fileId}': + 'files/translation-status', + 'post /v2/project/files/moves': 'files/move-files', + 'post /v2/project/files/orphaned': 'files/orphaned-files', + 'post /v2/project/setup/generate': 'context/generate-context', + 'get /v2/project/setup/should-generate': 'context/check-freshness', + 'get /v2/project/setup/status/{jobId}': 'context/context-status', + 'post /v2/translate': 'translation/translate-runtime', + 'post /v2/project/translations/enqueue': 'translation/queue', + 'post /v2/project/jobs/info': 'translation/job-status', + 'post /v2/projects': 'project/create-project', + 'get /v2/project/info/{projectId}': 'project/project-info', + 'post /v2/project/info/{projectId}': 'project/update-project', + 'post /v2/project/assets': 'project/upload-assets', + 'post /v2/project/branches/info': 'project/branch-info', + 'post /v2/project/branches/create': 'project/create-branch', + 'post /v2/project/tags/create': 'project/upsert-tag', +}; + +function pageSlug(entry) { + const key = `${entry.item.method.toLowerCase()} ${entry.item.path}`; + const slug = PAGES[key]; + if (!slug) { + throw new Error( + `No output slug mapped for operation "${key}". Add it to PAGES in ${fileURLToPath(import.meta.url)}.` + ); + } + return slug; +} + +function plainText(value) { + return value + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/`([^`]+)`/g, '$1') + .replace(/\s+/g, ' ') + .trim(); +} + +function completeSentence(value) { + return /[.!?]$/.test(value) ? value : `${value}.`; +} + +function normalizeFrontmatter(file, document) { + const slug = file.path.replace(/\.mdx$/, ''); + const page = Object.entries(PAGES).find(([, output]) => output === slug); + if (!page) { + throw new Error(`No operation mapped for generated page "${file.path}".`); + } + + const [operationKey] = page; + const separator = operationKey.indexOf(' '); + const method = operationKey.slice(0, separator); + const route = operationKey.slice(separator + 1); + const operation = document.paths?.[route]?.[method]; + if (!operation || typeof operation.summary !== 'string') { + throw new Error(`No OpenAPI operation found for "${operationKey}".`); + } + + const frontmatterEnd = file.content.indexOf('\n---', 4); + const body = file.content.slice(frontmatterEnd + 4); + const generatedFrontmatter = file.content.slice(4, frontmatterEnd); + const openapiStart = generatedFrontmatter.indexOf('_openapi:'); + if (frontmatterEnd === -1 || openapiStart === -1) { + throw new Error(`Could not parse generated frontmatter in "${file.path}".`); + } + + const summary = plainText(operation.summary); + const overview = completeSentence( + plainText(operation.description ?? operation.summary) + ); + const description = `${overview} API reference for ${summary}.`; + const openapiMetadata = generatedFrontmatter.slice(openapiStart).trimEnd(); + + file.content = `--- + +title: ${JSON.stringify(summary)} +description: ${JSON.stringify(description)} +method: ${method.toUpperCase()} +full: true +${openapiMetadata} +---${body}`; +} + +// Marker Fumadocs writes into every generated MDX page. +const GENERATED_MARKER = 'This file was generated by Fumadocs'; + +// Recursively delete only Fumadocs-generated `.mdx` pages, leaving +// hand-authored files (every meta.json) in place. Empty group folders left +// behind after deletion are pruned. +function cleanGenerated(dir = OUTPUT_DIR) { + if (!fs.existsSync(dir)) return; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const target = path.join(dir, entry.name); + if (entry.isDirectory()) { + cleanGenerated(target); + if (fs.readdirSync(target).length === 0) fs.rmdirSync(target); + continue; + } + if (!entry.name.endsWith('.mdx')) continue; + const content = fs.readFileSync(target, 'utf-8'); + if (content.includes(GENERATED_MARKER)) fs.unlinkSync(target); + } +} + +async function main() { + console.log('=== OpenAPI Docs Generator ===\n'); + cleanGenerated(); + + await generateFiles({ + input: openapi, + output: OUTPUT_DIR, + per: 'operation', + groupBy: (entry) => path.dirname(pageSlug(entry)), + name: (entry) => path.basename(pageSlug(entry)), + beforeWrite(files) { + const document = this.documents['gt-api']?.dereferenced; + if (!document) { + throw new Error('Could not load the gt-api OpenAPI document.'); + } + for (const file of files) normalizeFrontmatter(file, document); + }, + }); + + console.log(`\nGenerated operation pages into ${OUTPUT_DIR}`); +} + +main().catch((e) => { + console.error('Failed to generate OpenAPI docs', e); + process.exit(1); +}); diff --git a/apps/content/src/lib/openapi.ts b/apps/content/src/lib/openapi.ts index 90ce8a033..dc3f8e708 100644 --- a/apps/content/src/lib/openapi.ts +++ b/apps/content/src/lib/openapi.ts @@ -8,7 +8,10 @@ import { createOpenAPI } from 'fumadocs-openapi/server'; // differs between this app and the landing app that renders the same content. export const openapi = createOpenAPI({ input: () => ({ - 'gt-api': path.join(process.cwd(), '../../docs/en-US/api/openapi.yaml'), + 'gt-api': path.join( + process.cwd(), + '../../docs/en-US/platform/openapi/openapi.yaml' + ), }), proxyUrl: '/api/proxy', }); diff --git a/devlog/en-US/local-edits.mdx b/devlog/en-US/local-edits.mdx index 9b74fc255..f7d54689c 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.1 and later, [`translate`](/docs/cli/reference/commands/translate) runs the save step by default; pass `--no-save-local` to skip it._ + --- ## 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/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/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 855f95f69..64aaf984c 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] @@ -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 461ed3da7..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` | Detect and save local edits before downloading. | `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/cli/reference/config.mdx b/docs/en-US/cli/reference/config.mdx index 3419d636a..2db24c49d 100644 --- a/docs/en-US/cli/reference/config.mdx +++ b/docs/en-US/cli/reference/config.mdx @@ -78,7 +78,7 @@ Each file type accepts the following keys. - `include` — an array of glob patterns matching files to translate. Use the `[locale]` placeholder: the CLI replaces it with `defaultLocale` to find source files, and with each target code to save translations. Required for every type except `gt`. - `exclude` — an array of glob patterns to skip. The `[locale]` placeholder is optional here; use `[locales]` to exclude a path across all locales. -- `transform` — remaps output file names. A string with a `*` wildcard remaps the extension (for example `*.[locale].json`). An object with `match` and `replace` supports regex capture groups and the `{locale}` placeholder. +- `transform` — remaps output file names. A string with a `*` wildcard remaps the extension (for example `*.[locale].json`). An object with `match` and `replace` supports regex capture groups and the locale placeholders in [Locale placeholders](#locale-placeholders). - `transformationFormat` — outputs translated files in a different format than the source. For example, `pot` sources with `"transformationFormat": "PO"` produce `.po` files. - `requiresReview` — gates translated files behind human review. Accepts `true`/`false`, or an object with `include` and `exclude` glob arrays where `exclude` takes precedence. - `output` — for `gt` files only, the local save path with a `[locale]` placeholder, such as `public/i18n/[locale].json`. @@ -102,6 +102,40 @@ Each file type accepts the following keys. } ``` +### Locale placeholders [#locale-placeholders] + +The `replace` value of an object `transform` accepts `{...}` placeholders that expand to properties of the target locale. Unrecognized names are left in the output as literal text. + +| Placeholder | Description | Example for `pt-BR` | +| --- | --- | --- | +| `{locale}` | The locale exactly as written in [`locales`](#locales). `{localeCode}` is an alias. | `pt-BR` | +| `{localeName}` | English name of the locale, including its region. | `Brazilian Portuguese` | +| `{localeNativeName}` | Native name of the locale, including its region. | `português (Brasil)` | +| `{languageCode}` | Language subtag on its own. | `pt` | +| `{regionCode}` | Region subtag on its own. | `BR` | +| `{scriptCode}` | Script subtag on its own. | `Latn` | +| `{minimizedCode}` | Shortest unambiguous form of the tag. | `pt` | +| `{maximizedCode}` | Fully expanded tag, including script. | `pt-Latn-BR` | +| `{emoji}` | Flag emoji associated with the locale. | 🇧🇷 | + +The remaining [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) fields are also accepted by name, including `languageName`, `nativeLanguageName`, `regionName`, `nativeRegionName`, `scriptName`, `nativeScriptName`, `nameWithRegionCode`, `nativeNameWithRegionCode`, `maximizedName`, `nativeMaximizedName`, `minimizedName`, and `nativeMinimizedName`. + +`{locale}` uses the spelling from your configuration rather than the canonical BCP-47 form, so a locale configured as `fr-ca` produces `fr-ca` and not `fr-CA`. This matches the `[locale]` placeholder in `include`, `exclude`, and `output`, so file paths and localized URLs agree. Use `{minimizedCode}`, `{maximizedCode}`, or `{regionCode}` when you need a normalized tag instead. + +```json title="gt.config.json" +{ + "files": { + "json": { + "include": ["locales/[locale]/**/*.json"], + "transform": { + "match": "locales/(.*)/(.*)\\.json", + "replace": "locales/{locale}/$2.{languageCode}.json" + } + } + } +} +``` + ## `fonts` [#fonts] **Type** `object` · **Optional** · **Default** — @@ -128,7 +162,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/integrations/mintlify/guides/translating-content.mdx b/docs/en-US/integrations/mintlify/guides/translating-content.mdx index 769348e70..eaa98a88a 100644 --- a/docs/en-US/integrations/mintlify/guides/translating-content.mdx +++ b/docs/en-US/integrations/mintlify/guides/translating-content.mdx @@ -43,4 +43,4 @@ Translation happens at the Markdown and MDX syntax level, so your structure and ## Context-aware translation [#context] -Translations are produced by AI agents that understand technical terminology and the surrounding content, so meaning and product terms stay consistent across languages. To steer terminology and tone across your Project, define translation context in the Dashboard. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). +Translations are produced by AI agents that understand technical terminology and the surrounding content, so meaning and product terms stay consistent across languages. To steer terminology and tone across your Project, define translation context in the Dashboard. See [Defining context for translations](/docs/platform/dashboard/guides/defining-context-for-translations). diff --git a/docs/en-US/overview/for-coding-agents.mdx b/docs/en-US/overview/for-coding-agents.mdx index ca564ab31..c188e1a9e 100644 --- a/docs/en-US/overview/for-coding-agents.mdx +++ b/docs/en-US/overview/for-coding-agents.mdx @@ -238,5 +238,5 @@ Most setup is the same across agents; these are the few places the guidance diff Agents are reliable for mechanical i18n work, but translation quality and configuration still need a human. Use this split: - **Hand to the agent:** wrapping user-facing copy in [``](/docs/react/reference/components/t), adding [`useGT()`](/docs/react/reference/hooks/use-gt) for standalone strings, scaffolding `gt.config.json`, and running [`npx gt init`](/docs/cli/reference/commands/init). -- **Verify by hand:** the [translation context](/docs/overview/key-concepts#context) (Glossary and Directives) the agent writes, the locale configuration (`defaultLocale` and `locales`), and that dynamic or private values are wrapped in [``](/docs/react/reference/components/var). +- **Verify by hand:** the [translation context](/docs/overview/key-concepts#context) (Glossary and Custom Prompts) the agent writes, the locale configuration (`defaultLocale` and `locales`), and that dynamic or private values are wrapped in [``](/docs/react/reference/components/var). - **Never let the agent do:** hand-editing generated translation files, or hardcoding already-translated strings instead of translating source copy with the CLI. diff --git a/docs/en-US/overview/key-concepts.mdx b/docs/en-US/overview/key-concepts.mdx index 836425ee0..e610128f2 100644 --- a/docs/en-US/overview/key-concepts.mdx +++ b/docs/en-US/overview/key-concepts.mdx @@ -81,9 +81,9 @@ Context helps General Translation: General Translation applies context through **Context Groups**, which combine two parts: - **Glossary** defines key terms: product names, feature names, and technical terms that need consistent treatment. -- **Directives** define style and tone: audience, formality, conventions, and formatting. +- **Custom Prompts** define style and tone: audience, formality, conventions, and formatting. -See [Adding translation context](/docs/platform/dashboard/guides/adding-translation-context) to set this up. +See [Defining context for translations](/docs/platform/dashboard/guides/defining-context-for-translations) to set this up. ## Static and dynamic content [#content] 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/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/dashboard/get-started.mdx b/docs/en-US/platform/dashboard/get-started.mdx index 9ec165600..acd6a4f48 100644 --- a/docs/en-US/platform/dashboard/get-started.mdx +++ b/docs/en-US/platform/dashboard/get-started.mdx @@ -6,7 +6,7 @@ navTitle: "Get started" related: links: - /docs/platform/dashboard/guides/reviewing-translations - - /docs/platform/dashboard/guides/adding-translation-context + - /docs/platform/dashboard/guides/defining-context-for-translations - /docs/platform/dashboard/guides/using-ask-ai - /docs/platform/dashboard/guides/managing-billing @@ -16,7 +16,7 @@ The Dashboard is the web app for reviewing translations, guiding the AI with con ## Key workflows [#key-workflows] -- **Define context and key terms for translation:** use Context Groups to guide terminology and style across Projects. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). +- **Define context and key terms for translation:** use Context Groups to guide terminology and style across Projects. See [Defining context for translations](/docs/platform/dashboard/guides/defining-context-for-translations). - **Review and edit translations:** compare locales, make manual edits, and inspect version history. See [Reviewing and editing translations](/docs/platform/dashboard/guides/reviewing-translations). - **Add annotations:** label entries, add notes, and discuss translation decisions with your team. See [Adding annotations](/docs/platform/dashboard/guides/adding-annotations). - **Automate the whole process:** see [Locadex](/docs/platform/locadex/quickstart) to automate localization setup and maintenance. @@ -26,12 +26,12 @@ The Dashboard is the web app for reviewing translations, guiding the AI with con ## Configuration [#configuration] -- **Create API keys:** use Project keys for a single Project and Organization keys for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys). -- **Manage team access:** invite members and manage Organization settings from the Organization scope. See [Organization settings](/docs/platform/dashboard/reference/organization-settings) and [Roles and permissions](/docs/platform/dashboard/reference/roles-and-permissions). +- **Create API keys:** use **Project > API Keys** for a single Project and **Organization > Developer > API Keys** for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys). +- **Manage team access:** invite members from **Organization > Settings > Members**. See [Organization settings](/docs/platform/dashboard/reference/organization-settings) and [Roles and permissions](/docs/platform/dashboard/reference/roles-and-permissions). - **Connect external services:** manage Organization-level authorizations under **Organization > Connections**. Connect providers or link resources under **Project > Integrations**. See [Organization settings](/docs/platform/dashboard/reference/organization-settings). - **Configure projects:** update Project name, source locale, CDN delivery, AI Context, and Project ID from Project settings. See [Project settings](/docs/platform/dashboard/reference/project-settings). - **Send events to your backend:** use webhooks to receive signed translation events. See [Webhooks](/docs/platform/dashboard/reference/webhooks). -- **Manage billing:** understand plans, usage-based pricing, buy prepaid credits, and set up auto-reload. See [Managing billing](/docs/platform/dashboard/guides/managing-billing). +- **Manage billing:** use **Organization > Settings > Billing** to review plans, buy prepaid credits, and set up auto-reload. See [Managing billing](/docs/platform/dashboard/guides/managing-billing). @@ -40,7 +40,7 @@ The Dashboard is the web app for reviewing translations, guiding the AI with con The Dashboard is organized into nested scopes: **Enterprise**, **Organization**, and **Project**. Most teams use Organizations and Projects. Enterprise is a layer for larger teams managing multiple Organizations. - **Enterprise** contains Organizations, members, billing, and security settings across multiple Organizations. -- **Organization** contains Projects, team members, shared context, API keys, webhooks, usage, Connections for authorized external services, and **Locadex > Automations** and **Locadex > Integrations**. +- **Organization** contains Projects, shared context, usage, Connections for authorized external services, and **Locadex > Automations** and **Locadex > Integrations**. **Developer** contains API keys and webhooks. **Settings** contains members, billing, plans, and Organization settings. - **Project** contains translations, Project context, API keys, settings, **Automations**, and **Integrations > Connected** and **Integrations > Catalog**. Use the switcher in the header to move between scopes. The sidebar changes based on the selected scope. @@ -53,15 +53,15 @@ If you do not see a page, check that you are in the right Organization or Projec **What is General Translation?** General Translation (GT) is the full-stack localization platform to translate your app, docs, and content into any language. GT combines open-source i18n libraries, an AI-native translation platform, and the purpose-built localization agent Locadex. We build a complete understanding of your codebase and product context by connecting your code, content, and translations. So you can bring the best translations of your product to the whole world. -**How do I get an API key?** Create a Project, then open **API Keys** at the Project or Organization level. Project keys are used for one Project. Organization keys support custom permissions for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys). +**How do I get an API key?** Create a Project, then open **Project > API Keys** or **Organization > Developer > API Keys**. Project keys are used for one Project. Organization keys support custom permissions for broader automation. See [API keys](/docs/platform/dashboard/reference/api-keys). **Can I edit translations after they are generated?** Yes. Use the **Translations** page to review and edit generated translations. You can also use annotations to label entries, add notes, and discuss translations with your team. See [Reviewing and editing translations](/docs/platform/dashboard/guides/reviewing-translations). -**What is context?** Context tells AI how to interpret and translate your product. It helps preserve brand and product names, resolve ambiguous words (like whether "cells" refers to rooms, phones, bacteria, or spreadsheets), and keep style consistent across your Organization and Projects. GT applies context through Context Groups, which include a Glossary for terminology and Directives for tone and style. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). +**What is context?** Context tells AI how to interpret and translate your product. It helps preserve brand and product names, resolve ambiguous words (like whether "cells" refers to rooms, phones, bacteria, or spreadsheets), and keep style consistent across your Organization and Projects. GT applies context through Context Groups, which include a Glossary for terminology and Custom Prompts for tone and style. See [Defining context for translations](/docs/platform/dashboard/guides/defining-context-for-translations). -**How do I share terminology across Projects?** Create a Context Group at the Organization level with shared Glossary terms and Directives, then assign it to multiple Projects. Changes to the group apply everywhere it is assigned. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). +**How do I share terminology across Projects?** Create a Context Group at the Organization level with shared Glossary terms and Custom Prompts, then assign it to multiple Projects. Changes to the group apply everywhere it is assigned. See [Defining context for translations](/docs/platform/dashboard/guides/defining-context-for-translations). -**How do I update existing translations after changing the Glossary?** Select relevant terms and use Apply Glossary to update existing translations that contain selected Glossary terms. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). +**How do I update existing translations after changing the Glossary?** Select relevant terms and use Apply Glossary to update existing translations that contain selected Glossary terms. See [Defining context for translations](/docs/platform/dashboard/guides/defining-context-for-translations). **How do I regenerate translations?** For code and uploaded translation files, use the CLI or Locadex to run a new translation pass; the Dashboard's **Translations** page does not run full-file retranslation. Linked Google Drive files can be regenerated with **Force retranslate** from the [Google Drive integration](/docs/integrations/google-drive/guides/managing-translations#force). diff --git a/docs/en-US/platform/dashboard/guides/adding-annotations.mdx b/docs/en-US/platform/dashboard/guides/adding-annotations.mdx index d4fc97392..39d1165f4 100644 --- a/docs/en-US/platform/dashboard/guides/adding-annotations.mdx +++ b/docs/en-US/platform/dashboard/guides/adding-annotations.mdx @@ -5,7 +5,7 @@ description: How to coordinate translation reviews by entry and locale with labe related: links: - /docs/platform/dashboard/guides/reviewing-translations - - /docs/platform/dashboard/guides/adding-translation-context + - /docs/platform/dashboard/guides/defining-context-for-translations - /docs/platform/dashboard/guides/using-ask-ai - /docs/platform/dashboard/guides/managing-billing diff --git a/docs/en-US/platform/dashboard/guides/adding-translation-context.mdx b/docs/en-US/platform/dashboard/guides/defining-context-for-translations.mdx similarity index 60% rename from docs/en-US/platform/dashboard/guides/adding-translation-context.mdx rename to docs/en-US/platform/dashboard/guides/defining-context-for-translations.mdx index 083b53fdb..10bc1f5b2 100644 --- a/docs/en-US/platform/dashboard/guides/adding-translation-context.mdx +++ b/docs/en-US/platform/dashboard/guides/defining-context-for-translations.mdx @@ -1,7 +1,7 @@ --- -title: Adding translation context -description: How to use Context Groups, Glossary, and Directives to guide AI translations. +title: Defining context for translations +description: How to keep terminology, voice, and style consistent across translations using Context Groups. related: links: - /docs/platform/dashboard/guides/reviewing-translations @@ -11,30 +11,28 @@ related: --- -Define how your product should be translated, including **terminology and style** that should stay consistent across Projects and across your whole Organization. - -General Translation applies reusable translation instructions through Context Groups. +Define the highest-quality translations of your product — including key terminology, brand voice, and style. Use Context Groups to apply shared guidance across your app, website, documentation, slides, and every other surface. ## Basic context workflow [#basic-context-workflow] -1. Open your Organization in the Dashboard. +1. Open your Organization in the **[Dashboard](https://dash.generaltranslation.com)**. 2. Go to the **Context** page. 3. Create a **Context Group**. -4. Add a **Glossary** (for terminology) and/or **Directives** (for style and tone). -5. **Assign** your Context Group to relevant Project(s). -6. Generate translations or apply updates to existing translations. +4. Add a **Glossary** (for terminology) and **Custom Prompts** (for style and tone). +5. **Assign** your Context Group to relevant Projects. +6. Generate your translations or apply updates to existing translations. ## What are Context Groups? [#context-groups] -**Context Groups** define consistent instructions for translation. Each Context Group includes a Glossary and Directives: +**Context Groups** are reusable instructions for translation. Assign a group to one or more Projects to apply consistent terminology and voice across translations. *For example, the same Context Group can be applied across your app, website, documentation, and sales decks.* -a) **Glossary** defines **key terms**: product and brand names, features, and technical terms. *Example: Locadex is the GT agent. This product name should never be translated.* +a) The **Glossary** defines wording and how key terms should be handled: including product terms, brand names, features, and technical terms. *Example: Keep "Locadex" untranslated in every locale.* -b) **Directives** define **style and tone**: audience, formality, conventions, and formatting. *Example: Use active voice, avoid jargon, and use formal “Sie.”* +b) **Custom Prompts** define how translations should sound: including audience, formality, voice, conventions, and formatting. *Example: Use active voice, avoid jargon, and use formal "Sie."* -All Context Groups are stored at the Organization-wide level. They can then be applied to one or more Projects. +Context Groups live at the Organization level. We recommend applying a Context Group across all your Projects, and then adding additional project-specific Context Groups if surfaces differ in terminology or style. ## Using key terms in the Glossary [#using-key-terms] @@ -50,9 +48,9 @@ Add terms to the Context Group that should own them. If the same term appears in Use **Search terms** to find an existing Glossary entry. -## Using style and tone in Directives [#using-style-tone] +## Using style and tone in Custom Prompts [#using-style-tone] -Use Directives for translation instructions that are broader than a single term. Directives are useful for: +Use Custom Prompts for translation instructions that are broader than a single term. Custom Prompts are useful for: - Style and tone - Target audience @@ -60,9 +58,9 @@ Use Directives for translation instructions that are broader than a single term. - Locale-specific style rules - Product or domain-specific instructions -Directives can be global or locale-specific. Use locale-specific directives when guidance should apply only to one target language or region. +Each Custom Prompt can apply globally or to one locale. Use a locale-specific Custom Prompt when guidance should apply only to one target language or region. -Use **Search directives** to filter the current Context Group. +Use **Search custom prompts** to filter the current Context Group. ## How to create and assign a Context Group [#create-assign-context] @@ -74,10 +72,10 @@ You can create a Context Group from your Organization page or from a specific Pr *Use the Organization-level flow when you want to create a shared group first, then assign it to one or more Projects.* -1. Open **Context** in the Organization sidebar. +1. Open **Context** in the **[Organization](https://dash.generaltranslation.com)** sidebar. 2. Click the plus sign and **Create new group**. 3. Enter a name and confirm. -4. Add relevant **Glossary** terms and **Directives**. +4. Use the **Glossary** and **Custom Prompts** tabs to add relevant context. 5. Open each relevant Project. 6. Assign the group from the Project's **Context** tab. 7. Use the **Translate** button to use AI to generate translations for Glossary terms for each target locale. @@ -91,7 +89,7 @@ Context Groups are applied every time AI generates translations, including Locad 1. Open **Context** in the Project sidebar. 2. Click the plus sign and **Create new group**. 3. Enter a name and confirm. Select the checkbox to **Autogenerate context** from your Project files. -4. Add relevant **Glossary** terms and **Directives**. +4. Use the **Glossary** and **Custom Prompts** tabs to add relevant context. 5. Use the **Translate** button to use AI to generate translations for Glossary terms for each target locale. When you create a Context Group from a Project, it is still created at the Organization level. GT automatically assigns it to the current Project. @@ -102,7 +100,9 @@ When you create a Context Group from a Project, it is still created at the Organ In most cases, you should directly assign or reassign Projects to Context Groups. -However, for major changes, you can also use **Export** to download a group's Glossary and Directives. Then use **Import** to fill empty Glossary and Directives fields from a supported file. +However, for major changes, you can also use **Export** to download a group's Glossary and Custom Prompts. Then use **Import** to populate an empty group's Glossary and Custom Prompts from a supported file. + +Exports label the prompt section `## Custom Prompts`. **Import** also accepts earlier exports that label it `## Directives`. ## Set priority when groups overlap [#priority] diff --git a/docs/en-US/platform/dashboard/guides/managing-billing.mdx b/docs/en-US/platform/dashboard/guides/managing-billing.mdx index ff1fffe59..1d53c42fe 100644 --- a/docs/en-US/platform/dashboard/guides/managing-billing.mdx +++ b/docs/en-US/platform/dashboard/guides/managing-billing.mdx @@ -5,15 +5,13 @@ description: How to manage plans, usage-based pricing, prepaid credits, and auto related: links: - /docs/platform/dashboard/guides/reviewing-translations - - /docs/platform/dashboard/guides/adding-translation-context + - /docs/platform/dashboard/guides/defining-context-for-translations - /docs/platform/dashboard/guides/adding-annotations - /docs/platform/dashboard/guides/using-ask-ai --- -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 **Organization > Usage**. Plans, credit balances, reload settings, and invoices live on **Organization > Settings > Billing**. ## Plans [#plans] @@ -28,21 +26,35 @@ 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**. 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. +- **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] - **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. See the [usage rates](https://generaltranslation.com/pricing/usage) page for current rates and calculation examples. +## Invoice history [#invoices] + +When invoices are available, **Organization > Settings > Billing** 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: +Your **credit balance** is a prepaid wallet for platform usage, shown on **Organization > Settings > Billing** and denominated in dollars ($1 = 1M credits). The balance is split into buckets: - **Purchased** — credits you purchased. - **Granted** — any one-time signup credit. @@ -52,17 +64,17 @@ 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 **Organization > Settings > Billing** 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] -Auto-reload keeps your balance topped up automatically when your balance falls below a certain threshold. It is off by default. To turn on, choose **Auto Reload** on the Billing page, turn on **Enable Auto Reload**, and set: +Auto-reload keeps your balance topped up automatically when your balance falls below a certain threshold. It is off by default. To turn on, choose **Auto Reload** on **Organization > Settings > Billing**, turn on **Enable Auto Reload**, and set: - **Minimum Balance** — when your balance goes below this, a reload is triggered. - **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 @@ -84,12 +96,12 @@ What happens at $0 depends on auto-reload: ### Upgrade to Starter [#to-starter] -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. +Because Starter has no monthly fee, upgrading is simply adding a payment method. On **Organization > Settings > Billing**, 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] 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/meta.json b/docs/en-US/platform/dashboard/guides/meta.json index 8231bdec4..9352b5534 100644 --- a/docs/en-US/platform/dashboard/guides/meta.json +++ b/docs/en-US/platform/dashboard/guides/meta.json @@ -2,7 +2,7 @@ "title": "Guides", "description": "Browse how-to Guides for using the General Translation Dashboard.", "pages": [ - "./adding-translation-context", + "./defining-context-for-translations", "./reviewing-translations", "./adding-annotations", "./using-ask-ai", diff --git a/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx b/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx index d3a019f03..7a60542e4 100644 --- a/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx +++ b/docs/en-US/platform/dashboard/guides/reviewing-translations.mdx @@ -4,7 +4,7 @@ title: Reviewing and editing translations description: How to review translations, make manual edits, and compare locales in the Dashboard. related: links: - - /docs/platform/dashboard/guides/adding-translation-context + - /docs/platform/dashboard/guides/defining-context-for-translations - /docs/platform/dashboard/guides/adding-annotations - /docs/platform/dashboard/guides/using-ask-ai - /docs/platform/dashboard/guides/managing-billing @@ -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/guides/using-ask-ai.mdx b/docs/en-US/platform/dashboard/guides/using-ask-ai.mdx index 0811368e5..592c46e7a 100644 --- a/docs/en-US/platform/dashboard/guides/using-ask-ai.mdx +++ b/docs/en-US/platform/dashboard/guides/using-ask-ai.mdx @@ -5,7 +5,7 @@ description: How to use Ask AI to answer product questions, open cited docs, and related: links: - /docs/platform/dashboard/guides/reviewing-translations - - /docs/platform/dashboard/guides/adding-translation-context + - /docs/platform/dashboard/guides/defining-context-for-translations - /docs/platform/dashboard/guides/adding-annotations - /docs/platform/dashboard/guides/managing-billing @@ -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. diff --git a/docs/en-US/platform/dashboard/reference/api-keys.mdx b/docs/en-US/platform/dashboard/reference/api-keys.mdx index f8a2b1878..eb8a48d48 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 > Developer > 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 | +| **Context** | Read Project and Organization context | Manage Context Groups, Glossary, and Custom Prompts | | **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 | -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] @@ -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..483e4937a 100644 --- a/docs/en-US/platform/dashboard/reference/organization-settings.mdx +++ b/docs/en-US/platform/dashboard/reference/organization-settings.mdx @@ -12,7 +12,7 @@ For larger teams, **Enterprises** provide an optional layer above Organizations. ## Inviting new members [#inviting-new-members] -Organization admins can invite new members by email. +Organization admins can invite new members by email from **Organization > Settings > Members**. Invitees receive a link to join the Organization. The link expires after 7 days. @@ -20,7 +20,7 @@ For Enterprise accounts, members added at the Enterprise level can access all ma ## Member roles [#member-roles] -The Members page shows everyone with access to your Organization. Roles control what members can see and do. +The **Organization > Settings > Members** page shows everyone with access to your Organization. Roles control what members can see and do. - **Admin** has full access to all Organization settings, Projects, members, billing, and translations. Admins can delete the Organization. - **Developer** has technical access to Projects, including API keys, GitHub integration, Locadex, and usage data. @@ -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 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. -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 > Settings > 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/dashboard/reference/webhooks.mdx b/docs/en-US/platform/dashboard/reference/webhooks.mdx index 2c6ca0ebd..75d1433c3 100644 --- a/docs/en-US/platform/dashboard/reference/webhooks.mdx +++ b/docs/en-US/platform/dashboard/reference/webhooks.mdx @@ -9,7 +9,7 @@ Webhooks send translation events to your backend as signed HTTP POST requests. U ## Create a webhook [#create-webhook] -1. Go to **Organization > Webhooks > Endpoints**. +1. Go to **Organization > Developer > Webhooks**. 2. Click **Add endpoint**. 3. Enter the endpoint URL where you want to receive events. The URL must use HTTPS. 4. Select the event types you want to subscribe to. @@ -115,7 +115,7 @@ Webhooks use **at-least-once delivery**. If your endpoint does not return a `2xx` response within 10 seconds, the delivery is retried with exponential backoff for up to **10 attempts**. -You can manually retry a failed delivery from **Organization > Webhooks > Events** in the Dashboard. +You can manually retry a failed delivery from **Organization > Developer > Webhook Events** in the Dashboard. Expand a failed attempt to inspect its **Error** field. For a non-`2xx` response, the error includes the HTTP status and may include a sanitized excerpt of the endpoint's response body. General Translation reads up to 4,096 bytes from the response and stores at most 500 characters for diagnostics. @@ -139,14 +139,14 @@ app.post("/webhooks/gt", (req, res) => { ## Manage endpoints [#manage-endpoints] -From **Organization > Webhooks > Endpoints**, you can: +From **Organization > Developer > Webhooks**, you can: - Enable or disable an endpoint without deleting it - Update the subscribed event types - Reveal the signing secret - Delete the endpoint -From **Organization > Webhooks > Events**, you can view delivery history, inspect individual attempts, and retry failed deliveries. +From **Organization > Developer > Webhook Events**, you can view delivery history, inspect individual attempts, and retry failed deliveries. ## Best practices [#best-practices] diff --git a/docs/en-US/platform/index.mdx b/docs/en-US/platform/index.mdx index 489eb4565..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/platform/openapi/openapi.yaml b/docs/en-US/platform/openapi/openapi.yaml index 823b09e5f..c4a87b5a2 100644 --- a/docs/en-US/platform/openapi/openapi.yaml +++ b/docs/en-US/platform/openapi/openapi.yaml @@ -4,29 +4,28 @@ 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 - `https://api2.gtx.dev`. The runtime translation endpoint (`POST /v2/translate`) - is served from `https://runtime2.gtx.dev`. + Most endpoints operate on a single project. All endpoints live under + `https://api.gtx.dev`. Authenticate every request with an API key as a bearer token in the standard `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 url: https://generaltranslation.com servers: - - url: https://api2.gtx.dev - description: Project and file API - - url: https://runtime2.gtx.dev - description: Runtime translation API (POST /v2/translate) + - url: https://api.gtx.dev + description: General Translation API security: - Bearer: [] tags: @@ -41,7 +40,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. @@ -234,6 +233,10 @@ paths: get: tags: [Context] summary: Check if context generation is needed + description: > + Check whether the Project needs translation context generated. This + deprecated endpoint is retained for backward compatibility and is no + longer called by current clients. deprecated: true operationId: shouldGenerateContext parameters: @@ -305,6 +308,10 @@ paths: get: tags: [Context] summary: Get context generation job status + description: > + Track a context generation job. This deprecated endpoint is retained + for backward compatibility; new integrations should use + `POST /v2/project/jobs/info`. deprecated: true operationId: getContextStatus parameters: @@ -568,6 +575,8 @@ paths: post: tags: [Branches] summary: Get branch information + description: > + Return the Project's default branch and any branches requested by name. operationId: getBranchInfo parameters: - $ref: '#/components/parameters/GtApiVersion' @@ -701,10 +710,219 @@ 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. Enabling CDN delivery also requires + `project:write`. + 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 + cdnEnabled: + type: boolean + default: false + description: Enable CDN delivery for the new project. + 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': + description: Missing, invalid, or non-organization API key. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: > + The API key lacks `org:projects:create` or is blocked by an access + policy, or `cdnEnabled` is true and the key lacks `project:write`. + 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/assets: + post: + tags: [Project] + summary: Upload project assets + description: > + Upload OpenType or TrueType fonts through a project and make them + available to Lottie translation workflows across its organization. + Each font is keyed by a normalized identity derived from its family, + weight, and italic style (from the supplied `family` and `style`, or + from the font metadata and file name). Re-uploading the same identity + overwrites the existing asset, so complete retries after a `500` + response are safe. + operationId: uploadProjectAssets + parameters: + - $ref: '#/components/parameters/GtApiVersion' + - $ref: '#/components/parameters/GtProjectId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [assets] + properties: + assets: + type: array + minItems: 1 + maxItems: 50 + items: + type: object + required: [assetType, content, fileName] + properties: + assetType: + type: string + enum: [FONT] + description: Asset type. Only `FONT` is supported. + content: + type: string + description: > + Base64-encoded font content, up to 20MB after + decoding. + fileName: + type: string + minLength: 1 + maxLength: 255 + description: > + Font file name ending in `.ttf` or `.otf`. + example: BrandSans.ttf + family: + type: string + minLength: 1 + maxLength: 255 + description: > + Font family name used by the Lottie file. When + omitted, the server derives it from the font + metadata or file name. + example: Brand Sans + style: + type: string + minLength: 1 + maxLength: 100 + description: > + Style or weight used with `family`, such as `Bold`, + `350`, or `Bold Italic`. Defaults to Regular (`400`) + when `family` is set. + example: Bold + responses: + '201': + description: Uploaded font assets. + content: + application/json: + schema: + type: object + required: [assets, count] + properties: + assets: + type: array + items: + type: object + properties: + id: + type: string + description: Stored organization asset ID. + example: asset_abc123 + assetKey: + type: string + description: > + Normalized identity in the form + `-[-i]`. + example: brandsans-700 + fileName: { type: string, example: BrandSans.ttf } + count: + type: number + description: Number of uploaded assets. + example: 1 + '400': + description: > + Invalid request body, invalid base64, an empty asset, an + unsupported file extension, an asset larger than 20MB, or a font + family that cannot be determined. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': { $ref: '#/components/responses/Unauthorized' } + '403': { $ref: '#/components/responses/Forbidden' } + '404': { $ref: '#/components/responses/NotFound' } + '413': + description: The JSON request body exceeds 100MB. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '429': { $ref: '#/components/responses/RateLimited' } + '500': + description: > + An asset could not be stored. Retry the complete request; each + font identity is upserted. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /v2/project/info/{projectId}: get: tags: [Project] summary: Get project information + description: > + Read the authenticated Project's name, Organization ID, locale settings, + and auto-approval setting. operationId: getProjectInfo parameters: - $ref: '#/components/parameters/GtApiVersion' @@ -736,7 +954,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' @@ -754,6 +972,9 @@ paths: type: object properties: defaultLocale: { type: string } + cdnEnabled: + type: boolean + description: Enable or disable CDN delivery. responses: '200': description: Project updated. @@ -772,6 +993,9 @@ paths: post: tags: [Jobs] summary: Get translation job status + description: > + Return normalized status information for one or more queued translation + or context generation jobs. operationId: getJobsInfo parameters: - $ref: '#/components/parameters/GtApiVersion' @@ -907,6 +1131,9 @@ paths: get: tags: [Files] summary: Get translation status for a file + description: > + Return translation progress and availability by locale for one source + file, along with its source metadata. operationId: getTranslationStatus parameters: - $ref: '#/components/parameters/GtApiVersion' @@ -1076,9 +1303,6 @@ paths: '404': { $ref: '#/components/responses/NotFound' } /v2/translate: - servers: - - url: https://runtime2.gtx.dev - description: Runtime translation API post: tags: [Translation] summary: Translate content at runtime @@ -1186,7 +1410,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: @@ -1222,7 +1447,7 @@ components: fileName: { type: string } fileFormat: type: string - description: File format, e.g. json, yaml, xml. + description: File format identifier, for example JSON, MDX, or LOTTIE. dataFormat: type: string description: Data format, e.g. STRING, JSX, ICU. diff --git a/docs/en-US/platform/openapi/overview.mdx b/docs/en-US/platform/openapi/overview.mdx index eac7edbb8..1ade14540 100644 --- a/docs/en-US/platform/openapi/overview.mdx +++ b/docs/en-US/platform/openapi/overview.mdx @@ -9,38 +9,38 @@ 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. ## API basics [#api-basics] -### Base URLs +### Base URL -- Use `https://api2.gtx.dev` for project and file endpoints. -- Use `https://runtime2.gtx.dev` for runtime translation, including `POST /v2/translate`. +All endpoints, including runtime translation with `POST /v2/translate`, live under `https://api.gtx.dev`. ### Authentication -Send your API key in the `x-gt-api-key` header. +Send your API key as a bearer token in the standard `Authorization` header. ```bash -curl https://api2.gtx.dev/v2/project/info/PROJECT_ID \ - -H "x-gt-api-key: gtx-api-..." +curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ + -H "Authorization: Bearer gtx-api-..." ``` 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, you must send `x-gt-project-id`. +- **Organization** with prefix `gtx-org-`: works across Projects. When using an Organization key on Project-scoped endpoints, send `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,19 +50,20 @@ 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. - `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. ### 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 +78,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/context/check-freshness.mdx b/docs/en-US/platform/openapi/reference/context/check-freshness.mdx index b13868abc..aaf5a7364 100644 --- a/docs/en-US/platform/openapi/reference/context/check-freshness.mdx +++ b/docs/en-US/platform/openapi/reference/context/check-freshness.mdx @@ -1,61 +1,22 @@ --- -title: Check context freshness -description: Check whether General Translation Project context is missing, stale, or ready to refresh. API reference for Check context freshness. - +title: "Check if context generation is needed" +description: "Check whether the Project needs translation context generated. This deprecated endpoint is retained for backward compatibility and is no longer called by current clients. API reference for Check if context generation is needed." method: GET +full: true +_openapi: + method: GET + route: /v2/project/setup/should-generate + toc: [] + structuredData: + headings: [] + contents: + - content: > + Check whether the Project needs translation context generated. This + deprecated endpoint is retained for backward compatibility and is no + longer called by current clients. --- -Reports whether the Project needs translation context generated. Use it before calling [Generate translation context](/docs/platform/openapi/reference/context/generate-context) to avoid unnecessary work. - -*Note: this endpoint is retained for backward compatibility and is no longer called by current clients.* - -## Overview [#overview] - -```http -GET https://api2.gtx.dev/v2/project/setup/should-generate -``` - -**Permission** `project:context:read` · **Rate limit** Medium (120/min) - -Check whether context generation is needed for the authenticated Project. - -## How it works [#how-it-works] - -- The Project's context is loaded and evaluated against its default locale. -- The response returns `shouldSetupProject: true` when the Project has no usable context yet, and `false` otherwise. -- The Project is resolved from the API key, so no request body or parameters are needed. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "shouldSetupProject": true -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:context:read`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X GET https://api2.gtx.dev/v2/project/setup/should-generate \ - -H "x-gt-api-key: gtx-api-..." -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/context/context-status.mdx b/docs/en-US/platform/openapi/reference/context/context-status.mdx index 4dbc882db..90f512ce8 100644 --- a/docs/en-US/platform/openapi/reference/context/context-status.mdx +++ b/docs/en-US/platform/openapi/reference/context/context-status.mdx @@ -1,77 +1,22 @@ --- -title: Get context generation status -description: Track the status of a General Translation context generation job. API reference for Get context generation status. - +title: "Get context generation job status" +description: "Track a context generation job. This deprecated endpoint is retained for backward compatibility; new integrations should use POST /v2/project/jobs/info. API reference for Get context generation job status." method: GET +full: true +_openapi: + method: GET + route: /v2/project/setup/status/{jobId} + toc: [] + structuredData: + headings: [] + contents: + - content: > + Track a context generation job. This deprecated endpoint is retained + for backward compatibility; new integrations should use `POST + /v2/project/jobs/info`. --- -Look up a context generation job created by [Generate translation context](/docs/platform/openapi/reference/context/generate-context) to check its progress. - -*Note: this endpoint is retained for backward compatibility. For new integrations, use [Get translation job status](/docs/platform/openapi/reference/translation/job-status), which reports status for any queued job.* - -## Overview [#overview] - -```http -GET https://api2.gtx.dev/v2/project/setup/status/:jobId -``` - -**Permission** `project:context:read` · **Rate limit** Medium (120/min) - -Poll a single context generation job by ID. - -## How it works [#how-it-works] - -- The job is looked up within the authenticated Project. An unknown job ID returns `404`. -- A completed job returns `{ "status": "completed" }`. -- Otherwise the response includes the job ID and a normalized status: `queued`, `processing`, `failed`, or `unknown`. Pending and queued jobs map to `queued`; processing and retrying jobs map to `processing`. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Path parameters - -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| `jobId` | Identifier of the context generation job. | `string` | Yes | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "jobId": "job_...", - "status": "processing" -} -``` - -A completed job returns: - -```json title="Response" -{ - "status": "completed" -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:context:read`. | -| `404` | Job not found. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X GET https://api2.gtx.dev/v2/project/setup/status/job_... \ - -H "x-gt-api-key: gtx-api-..." -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/context/generate-context.mdx b/docs/en-US/platform/openapi/reference/context/generate-context.mdx index 308c993fc..4bf5d6381 100644 --- a/docs/en-US/platform/openapi/reference/context/generate-context.mdx +++ b/docs/en-US/platform/openapi/reference/context/generate-context.mdx @@ -1,101 +1,19 @@ --- -title: Generate context -description: Generate General Translation Project glossary terms and translation instructions from source files. API reference for Generate translation context. - +title: "Generate translation context" +description: "Generate glossaries and translation instructions for the project. API reference for Generate translation context." method: POST +full: true +_openapi: + method: POST + route: /v2/project/setup/generate + toc: [] + structuredData: + headings: [] + contents: + - content: Generate glossaries and translation instructions for the project. --- -Queues a background job that generates Project-level translation context — glossary terms and translation instructions — from the source files you reference. Optionally generate per-locale glossaries for target locales. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/setup/generate -``` - -**Permission** `project:context:write` · **Rate limit** Medium (120/min) - -Build the context that guides future translations. To track the resulting job, use [Get context generation status](/docs/platform/openapi/reference/context/context-status) or [Get translation job status](/docs/platform/openapi/reference/translation/job-status). - -## How it works [#how-it-works] - -- Target locales that are the same dialect as the Project's default locale are ignored. -- Unless `force` is `true`, generation is skipped when the Project already has context and no requested target locale needs a glossary. In that case the response is `{ "status": "completed" }` and no job is queued. -- Otherwise a context generation job is enqueued and its ID is returned with `status: "queued"`. When target locales are supplied, the Project's current locales are also updated. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`files`](#files) | Source files to generate context from; cannot be empty. | `object[]` | No | — | -| `locales` | Target locales to generate per-locale glossaries for. | `string[]` | Yes | — | -| `force` | Regenerate context even when it already exists. | `boolean` | Yes | `false` | - -#### `files` [#files] - -**Type** `object[]` · **Required** - -Each element references one source file: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `fileId` | Stable file identifier; cannot be empty. | `string` | No | — | -| `versionId` | Version identifier; cannot be empty. | `string` | No | — | -| `branchId` | Branch the file is attached to. | `string` | Yes | — | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "setupJobId": "job_...", - "status": "queued" -} -``` - -When generation is not needed, the response is instead: - -```json title="Response" -{ - "status": "completed" -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, empty `files` array, or invalid locale. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:context:write`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/setup/generate \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "files": [ - { - "fileId": "file_...", - "versionId": "ver_..." - } - ], - "locales": ["es", "fr"] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/download-many.mdx b/docs/en-US/platform/openapi/reference/files/download-many.mdx index a7db5526f..844ac77e8 100644 --- a/docs/en-US/platform/openapi/reference/files/download-many.mdx +++ b/docs/en-US/platform/openapi/reference/files/download-many.mdx @@ -1,103 +1,19 @@ --- -title: Download files -description: Download multiple translated files from a General Translation Project in one request. API reference for Download files. - +title: "Download multiple files" +description: "Download up to 100 source or translated files in one request. API reference for Download multiple files." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/download + toc: [] + structuredData: + headings: [] + contents: + - content: Download up to 100 source or translated files in one request. --- -Downloads multiple source or translated files in a single request. Each entry selects a file by ID, and file content is returned as base64. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/download -``` - -**Permission** `project:files:read` · **Rate limit** Light (300/min) - -Fetch many files at once. To download a single file, use [Download file](/docs/platform/openapi/reference/files/download). - -## How it works [#how-it-works] - -- Send 1 to 100 file references. Each is resolved independently and the successful results are returned together. -- An entry without `locale` returns the source file; an entry with `locale` returns that translation. -- A missing `branchId` resolves to the default branch. A missing `versionId` uses the branch head version, unless `useLatestAvailableVersion` is set. -- File content is returned base64-encoded in the `data` field. `fileName` is present only on source files, and `locale` is present only on translated files. -- For `LOTTIE`, `data` is the base64-encoded, reassembled `.lottie` file. Decode it to bytes rather than UTF-8 text. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -The body is a JSON array of 1–100 file references. Each element has these fields: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `fileId` | Stable file identifier; cannot be blank. | `string` | No | — | -| `branchId` | Branch to read from. | `string` | Yes | Default branch | -| `versionId` | Specific version to download. | `string` | Yes | Branch head version | -| `locale` | Locale to download. Omit to download the source file. | `string` | Yes | — | -| `useLatestAvailableVersion` | Fall back to the latest available version when the requested version is missing. | `boolean` | Yes | `false` | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "files": [ - { - "id": "sf_...", - "branchId": "br_...", - "fileId": "file_...", - "versionId": "ver_...", - "fileName": "en/common.json", - "data": "eyJoZWxsbyI6ICJIZWxsbyJ9", - "metadata": {}, - "fileFormat": "JSON" - }, - { - "id": "tf_...", - "branchId": "br_...", - "fileId": "file_...", - "versionId": "ver_...", - "locale": "es", - "data": "eyJoZWxsbyI6ICJIb2xhIn0=", - "metadata": {}, - "fileFormat": "JSON" - } - ], - "count": 2 -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, or an entry is missing a valid `fileId`. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/download \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '[ - { "fileId": "file_...", "locale": "es" }, - { "fileId": "file_..." } - ]' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/download.mdx b/docs/en-US/platform/openapi/reference/files/download.mdx index 8ea183df5..f7967e39d 100644 --- a/docs/en-US/platform/openapi/reference/files/download.mdx +++ b/docs/en-US/platform/openapi/reference/files/download.mdx @@ -1,78 +1,21 @@ --- -title: Download file -description: Download a single translated file from a General Translation Project for a locale or version. API reference for Download file. - +title: "Download a single file" +description: "Download a single source or translated file. Prefer the batch POST endpoint. API reference for Download a single file." method: GET +full: true +_openapi: + method: GET + route: /v2/project/files/download/{fileId} + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Download a single source or translated file. Prefer the batch POST + endpoint. --- -Downloads one source or translated file by ID. The file content is returned as base64. - -*Note: prefer [Download files](/docs/platform/openapi/reference/files/download-many) for new integrations. This single-file endpoint is retained for backward compatibility.* - -## Overview [#overview] - -```http -GET https://api2.gtx.dev/v2/project/files/download/:fileId -``` - -**Permission** `project:files:read` · **Rate limit** Light (300/min) - -Fetch one file. To download many files in one call, use [Download files](/docs/platform/openapi/reference/files/download-many). - -## How it works [#how-it-works] - -- Without a `locale` query parameter, the source file is returned. With `locale`, the matching translation is returned. -- A missing `branchId` resolves to the default branch. A missing `versionId` uses the branch head version. -- The file content is returned base64-encoded in the `data` field. A missing file returns `404`. -- For `LOTTIE`, `data` is the base64-encoded, reassembled `.lottie` file. Decode it to bytes rather than UTF-8 text. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Path parameters - -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| `fileId` | Stable file identifier to download. | `string` | Yes | - -### Query parameters - -| Parameter | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `locale` | Locale to download. Omit to download the source file. | `string` | Yes | — | -| `branchId` | Branch to read from. | `string` | Yes | Default branch | -| `versionId` | Specific version to download. | `string` | Yes | Branch head version | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "data": "eyJoZWxsbyI6ICJIb2xhIn0=" -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Missing `fileId`, or `branchId`/`versionId` is not a string. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `404` | File not found. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X GET "https://api2.gtx.dev/v2/project/files/download/file_...?locale=es" \ - -H "x-gt-api-key: gtx-api-..." -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/file-info.mdx b/docs/en-US/platform/openapi/reference/files/file-info.mdx index 0ccea93d9..2e98a37af 100644 --- a/docs/en-US/platform/openapi/reference/files/file-info.mdx +++ b/docs/en-US/platform/openapi/reference/files/file-info.mdx @@ -1,110 +1,19 @@ --- -title: Get file information -description: Inspect General Translation source file metadata, versions, locales, and translation state. API reference for Get file information. - +title: "Get file metadata" +description: "Get detailed metadata for specific source and translated files. API reference for Get file metadata." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/info + toc: [] + structuredData: + headings: [] + contents: + - content: Get detailed metadata for specific source and translated files. --- -Returns metadata for source and translated files by reference. Query source files, translated files, or both in one request. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/info -``` - -**Permission** `project:files:read` · **Rate limit** Default (200/min) - -Look up file metadata without downloading content. For per-locale translation progress on a single file, use [Get translation status](/docs/platform/openapi/reference/files/translation-status). - -## How it works [#how-it-works] - -- Provide `sourceFiles`, `translatedFiles`, or both. Each list is resolved independently and returned in its own array. -- Only files that exist are returned; unmatched references are omitted rather than causing an error. -- The response contains metadata only (locales, formats, timestamps), not file content. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `sourceFiles` | Source file references to look up. | `object[]` | Yes | — | -| `translatedFiles` | Translated file references to look up. | `object[]` | Yes | — | - -Each `sourceFiles` element requires `fileId`, `versionId`, and `branchId`. Each `translatedFiles` element requires `fileId`, `versionId`, `branchId`, and `locale`. All values cannot be blank. - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "sourceFiles": [ - { - "branchId": "br_...", - "fileId": "file_...", - "versionId": "ver_...", - "fileName": "en/common.json", - "fileFormat": "JSON", - "dataFormat": "JSON", - "createdAt": "2026-01-01T00:00:00.000Z", - "updatedAt": "2026-01-01T00:00:00.000Z", - "publishedAt": null, - "locales": ["es", "fr"], - "sourceLocale": "en" - } - ], - "translatedFiles": [ - { - "branchId": "br_...", - "fileId": "file_...", - "versionId": "ver_...", - "fileFormat": "JSON", - "dataFormat": "JSON", - "createdAt": "2026-01-01T00:00:00.000Z", - "updatedAt": "2026-01-01T00:00:00.000Z", - "approvedAt": null, - "publishedAt": null, - "completedAt": "2026-01-01T00:00:00.000Z", - "locale": "es" - } - ] -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid file query. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/info \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "sourceFiles": [ - { - "fileId": "file_...", - "versionId": "ver_...", - "branchId": "br_..." - } - ] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/move-files.mdx b/docs/en-US/platform/openapi/reference/files/move-files.mdx index 94675a8a8..0a68f7f75 100644 --- a/docs/en-US/platform/openapi/reference/files/move-files.mdx +++ b/docs/en-US/platform/openapi/reference/files/move-files.mdx @@ -1,106 +1,19 @@ --- -title: Move files -description: Move or rename files in a General Translation Project. API reference for Move files. - +title: "Move or rename files" +description: "Clone source files and their translations under new file IDs. API reference for Move or rename files." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/moves + toc: [] + structuredData: + headings: [] + contents: + - content: Clone source files and their translations under new file IDs. --- -Moves or renames files by cloning each source file and its translations under a new file ID and name. Send one entry per file to move. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/moves -``` - -**Permission** `project:files:write` · **Rate limit** Medium (120/min) - -Reflect renamed or relocated source files without losing their translations. To detect which files have become stale, use [Get orphaned files](/docs/platform/openapi/reference/files/orphaned-files). - -## How it works [#how-it-works] - -- Each move clones the existing source file and its translations to the `newFileId` and `newFileName`, preserving the translations. -- A missing `branchId` resolves to the default branch. A provided `branchId` must belong to the Project, otherwise the request returns `404`. -- An empty `moves` array returns an empty result set without error. -- The response reports a per-move result and a summary count of total, succeeded, and failed moves. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`moves`](#moves) | Array of file moves to process. | `object[]` | No | — | -| `branchId` | Branch the files are on. | `string` | Yes | Default branch | - -#### `moves` [#moves] - -**Type** `object[]` - -Each element describes one file move: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `oldFileId` | Current file identifier; cannot be blank. | `string` | No | — | -| `newFileId` | New file identifier; cannot be blank. | `string` | No | — | -| `newFileName` | New file name; cannot be blank. | `string` | No | — | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "results": [ - { - "oldFileId": "file_old...", - "newFileId": "file_new...", - "success": true, - "newSourceFileId": "sf_...", - "clonedTranslationsCount": 2 - } - ], - "summary": { - "total": 1, - "succeeded": 1, - "failed": 0 - } -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`. | -| `404` | Provided `branchId` not found in the Project. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/moves \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "moves": [ - { - "oldFileId": "file_old...", - "newFileId": "file_new...", - "newFileName": "en/renamed.json" - } - ] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/orphaned-files.mdx b/docs/en-US/platform/openapi/reference/files/orphaned-files.mdx index fcfd64444..bd99e31bf 100644 --- a/docs/en-US/platform/openapi/reference/files/orphaned-files.mdx +++ b/docs/en-US/platform/openapi/reference/files/orphaned-files.mdx @@ -1,82 +1,21 @@ --- -title: Get orphaned files -description: Find General Translation files that are no longer connected to current source files. API reference for Get orphaned files. - +title: "Find orphaned files" +description: "Return files on a branch that are not present in the provided file ID list. API reference for Find orphaned files." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/orphaned + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Return files on a branch that are not present in the provided file ID + list. --- -Returns files on a branch whose file IDs are not in the list of current file IDs you provide. It is used to detect files that were moved, renamed, or deleted locally. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/orphaned -``` - -**Permission** `project:files:read` · **Rate limit** Medium (120/min) - -Detect stale files before reconciling a branch. To then move or rename them, use [Move files](/docs/platform/openapi/reference/files/move-files). - -## How it works [#how-it-works] - -- The branch's head files are compared against the `fileIds` you send. -- Any file on the branch whose `fileId` is not in that list is returned as orphaned. -- The `branchId` must belong to the Project, otherwise the request returns `404`. -- An empty `fileIds` list marks every file on the branch as orphaned. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `branchId` | Branch to inspect; required. | `string` | No | — | -| `fileIds` | Current file IDs to keep. Files not in this list are orphaned. | `string[]` | Yes | `[]` | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "orphanedFiles": [ - { - "fileId": "file_...", - "versionId": "ver_...", - "fileName": "en/removed.json" - } - ] -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, or missing `branchId`. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `404` | Branch not found. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/orphaned \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "branchId": "br_...", - "fileIds": ["file_a...", "file_b..."] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/publish-files.mdx b/docs/en-US/platform/openapi/reference/files/publish-files.mdx index eb8caf9f2..1e518e872 100644 --- a/docs/en-US/platform/openapi/reference/files/publish-files.mdx +++ b/docs/en-US/platform/openapi/reference/files/publish-files.mdx @@ -1,102 +1,21 @@ --- -title: Publish files -description: Mark a General Translation Project's translated files as published so they are ready for delivery. API reference for Publish files. - +title: "Publish or unpublish files" +description: "Publish or unpublish translated files to the CDN. Requires CDN to be enabled. API reference for Publish or unpublish files." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/publish + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Publish or unpublish translated files to the CDN. Requires CDN to be + enabled. --- -Publishes or unpublishes translated files to the General Translation CDN. Set `publish` per file to control delivery, and receive a per-file, per-locale result. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/publish -``` - -**Permission** `project:files:write` · **Rate limit** Default (200/min) - -Control which translations the CDN serves. The Project must have the CDN enabled. - -## How it works [#how-it-works] - -- The Project must have the CDN enabled. Otherwise the request fails with `400`. -- For each file, the source file's published state is updated. Every completed translation of that file is then published or unpublished and its CDN cache entry is written or deleted. -- When `publish` is `true` and a translation's data is missing or too large to publish, that locale is reported as failed. A too-large file that was previously published is also unpublished. -- `LOTTIE` files are not served from the CDN because the edge cannot reassemble the binary bundle. The endpoint may still return `success: true`, which means the publish request was processed, not that the file is CDN-accessible. Download translated `.lottie` files through the file endpoints instead. -- When `publish` is `false`, the translations are unpublished and removed from the CDN cache. -- Processing is per file and per locale, so the response contains one result entry for each translation acted on. A source file that is not found is reported as a failed result rather than failing the whole request. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`files`](#files) | Array of files to publish or unpublish; cannot be empty. | `object[]` | No | — | - -#### `files` [#files] - -**Type** `object[]` · **Required** - -Each element identifies a file and the desired published state: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `fileId` | Stable file identifier. | `string` | No | — | -| `versionId` | Version identifier for this content. | `string` | No | — | -| `publish` | `true` to publish, `false` to unpublish. | `boolean` | No | — | -| `branchId` | Branch the file is attached to. | `string` | Yes | Default branch | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "results": [ - { - "fileId": "file_...", - "versionId": "ver_...", - "locale": "es", - "branchId": "br_...", - "success": true - } - ] -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, or the CDN is not enabled for the Project. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/publish \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "files": [ - { - "fileId": "file_...", - "versionId": "ver_...", - "publish": true - } - ] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/submit-diffs.mdx b/docs/en-US/platform/openapi/reference/files/submit-diffs.mdx index 6fce3dc9c..96e799e5a 100644 --- a/docs/en-US/platform/openapi/reference/files/submit-diffs.mdx +++ b/docs/en-US/platform/openapi/reference/files/submit-diffs.mdx @@ -1,98 +1,19 @@ --- -title: Submit file diffs -description: Submit diffs for changed source or translated content to a General Translation Project instead of uploading full files. API reference for Submit file diffs. - +title: "Submit translation diffs" +description: "Overwrite translations with user-provided localized content. API reference for Submit translation diffs." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/diffs + toc: [] + structuredData: + headings: [] + contents: + - content: Overwrite translations with user-provided localized content. --- -Overwrites stored translations with locally edited content for files that have changed. Send one entry per changed file and locale, so you can sync local edits without re-uploading every file. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/diffs -``` - -**Permission** `project:files:write` · **Rate limit** Medium (120/min) - -Push local translation edits back to a Project. To replace whole files instead, use [Upload translations](/docs/platform/openapi/reference/files/upload-translations). - -## How it works [#how-it-works] - -- Entries are grouped by `branchId`, `fileId`, `versionId`, and `locale`. Only the first entry per group is applied, so duplicate groups in one request are deduplicated. -- Entries with empty `localContent` are skipped. -- For each remaining group, the stored translation is overwritten with `localContent`. A missing `branchId` resolves to the default branch. -- The response reports how many translations were processed and how many entries were received. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`diffs`](#diffs) | Array of diff entries; cannot be empty. | `object[]` | No | — | - -#### `diffs` [#diffs] - -**Type** `object[]` · **Required** - -Each element describes one changed file and locale: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `localContent` | The full local (edited) content to store for this translation. | `string` | No | — | -| `locale` | Locale of the edited content; cannot be empty. | `string` | No | — | -| `fileId` | Stable file identifier. | `string` | No | — | -| `versionId` | Version identifier for this content. | `string` | No | — | -| `diff` | Diff of the changed content. | `string` | No | — | -| `branchId` | Branch the file is attached to. | `string` | Yes | Default branch | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "filesProcessed": 1, - "entriesReceived": 1, - "message": "Processed 1 translation(s)" -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, or the `diffs` array is empty. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/diffs \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "diffs": [ - { - "fileId": "file_...", - "versionId": "ver_...", - "locale": "es", - "diff": "@@ -1 +1 @@\n-Hola\n+Hola, mundo", - "localContent": "{\"hello\": \"Hola, mundo\"}" - } - ] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/translation-status.mdx b/docs/en-US/platform/openapi/reference/files/translation-status.mdx index f4cfaaeae..ed1d8fcf5 100644 --- a/docs/en-US/platform/openapi/reference/files/translation-status.mdx +++ b/docs/en-US/platform/openapi/reference/files/translation-status.mdx @@ -1,96 +1,21 @@ --- -title: Get translation status -description: Check translation progress and availability by file and locale in a General Translation Project. API reference for Get translation status. - +title: "Get translation status for a file" +description: "Return translation progress and availability by locale for one source file, along with its source metadata. API reference for Get translation status for a file." method: GET +full: true +_openapi: + method: GET + route: /v2/project/translations/files/status/{fileId} + toc: [] + structuredData: + headings: [] + contents: + - content: > + Return translation progress and availability by locale for one source + file, along with its source metadata. --- -Returns per-locale translation status for a single source file, along with the source file's metadata. Use it to poll whether translations are completed, approved, or published. - -## Overview [#overview] - -```http -GET https://api2.gtx.dev/v2/project/translations/files/status/:fileId -``` - -**Permission** `project:files:read` · **Rate limit** Default (200/min) - -Track translation progress for one file. To look up metadata for many files at once, use [Get file information](/docs/platform/openapi/reference/files/file-info). - -## How it works [#how-it-works] - -- The source file is resolved by `fileId` on the given branch. A missing `branchId` resolves to the default branch, and a missing `versionId` uses the branch head version. -- The response lists one entry per locale on the source file. For locales without a translation yet, the timestamp fields are `null`. -- If no source file is found, the request returns `404`. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Path parameters - -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| `fileId` | Stable file identifier to check. | `string` | Yes | - -### Query parameters - -| Parameter | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `versionId` | Specific version to check. | `string` | Yes | Branch head version | -| `branchId` | Branch to read from. | `string` | Yes | Default branch | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "translations": [ - { - "locale": "es", - "completedAt": "2026-01-01T00:00:00.000Z", - "approvedAt": null, - "publishedAt": null, - "createdAt": "2026-01-01T00:00:00.000Z", - "updatedAt": "2026-01-01T00:00:00.000Z" - } - ], - "sourceFile": { - "id": "sf_...", - "branchId": "br_...", - "fileId": "file_...", - "versionId": "ver_...", - "fileName": "en/common.json", - "sourceLocale": "en", - "fileFormat": "JSON", - "dataFormat": "JSON", - "createdAt": "2026-01-01T00:00:00.000Z", - "updatedAt": "2026-01-01T00:00:00.000Z", - "locales": ["es"] - } -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Missing `fileId`. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `404` | No source file found, or no translations found. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X GET "https://api2.gtx.dev/v2/project/translations/files/status/file_...?branchId=br_..." \ - -H "x-gt-api-key: gtx-api-..." -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/upload-source.mdx b/docs/en-US/platform/openapi/reference/files/upload-source.mdx index 252d35147..0a7403235 100644 --- a/docs/en-US/platform/openapi/reference/files/upload-source.mdx +++ b/docs/en-US/platform/openapi/reference/files/upload-source.mdx @@ -1,115 +1,21 @@ --- -title: Upload source files -description: Upload one or more source files to a General Translation Project before queuing translation. API reference for Upload source files. - +title: "Upload source files" +description: "Upload one or more source files to the project. Max 100 files per request. API reference for Upload source files." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/upload-files + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Upload one or more source files to the project. Max 100 files per + request. --- -Send one to 100 source files per request, with each file's content base64-encoded, to add them to a Project for translation. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/upload-files -``` - -**Permission** `project:files:write` · **Rate limit** Medium (120/min) - -Upload the source (untranslated) files for a Project. To upload already-translated files, use [Upload translations](/docs/platform/openapi/reference/files/upload-translations). To then translate the uploaded files, see [Queue translations](/docs/platform/openapi/reference/translation/queue). - -## How it works [#how-it-works] - -- Each file's `content` is base64-encoded and decoded server-side; invalid base64 is rejected. -- For `fileFormat: "LOTTIE"`, `content` must be a base64-encoded dotLottie (`.lottie`) ZIP file. The service stores the original bundle so translated animation data can be reassembled with its images, manifest, audio, and other assets at download. -- A missing `fileId` is derived by hashing the `fileName`; a missing `versionId` is derived by hashing the file content, so re-uploading identical content is idempotent per version. -- Files are attached to the default branch unless a valid `branchId` is provided. An unknown `branchId` returns `400`. -- If `sourceLocale` is sent and differs from the Project's current default locale, the Project default locale is updated. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`data`](#data) | Array of files to upload (1–100). | `object[]` | No | — | -| `sourceLocale` | Source locale for the uploaded files. | `string` | Yes | Project default locale | - -#### `data` [#data] - -**Type** `object[]` · **Required** - -Each element is `{ "source": { ... } }`, where `source` has these fields: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `content` | Base64-encoded file content. Max file size applies. | `string` | No | — | -| `fileName` | File name; cannot be empty. | `string` | No | — | -| `fileFormat` | File format identifier (for example, `JSON`, `MDX`, or `LOTTIE`). | `string` | No | — | -| `locale` | Locale of the source content; cannot be empty. | `string` | No | — | -| `dataFormat` | Data format for structured content. | `string` | Yes | — | -| `fileId` | Stable file identifier. | `string` | Yes | Hash of `fileName` | -| `versionId` | Version identifier for this content. | `string` | Yes | Hash of content | -| `branchId` | Branch to attach the file to. | `string` | Yes | Default branch | -| `formatMetadata` | Extra format-specific metadata. | `object` | Yes | — | - -## Response [#response] - -**Status** `201 Created` - -```json title="Response" -{ - "uploadedFiles": [ - { - "branchId": "br_...", - "fileId": "file_...", - "versionId": "ver_...", - "fileName": "en/common.json", - "fileFormat": "JSON", - "dataFormat": "JSON" - } - ], - "count": 1, - "message": "Successfully uploaded 1 source file(s)" -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, invalid locale/format, decode failure, file too large, or unknown `branchId`. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`. | -| `429` | Rate limit exceeded. | -| `503` | Server busy; retry with backoff. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/upload-files \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "sourceLocale": "en", - "data": [ - { - "source": { - "content": "eyJoZWxsbyI6ICJIZWxsbyJ9", - "fileName": "en/common.json", - "fileFormat": "JSON", - "locale": "en" - } - } - ] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/files/upload-translations.mdx b/docs/en-US/platform/openapi/reference/files/upload-translations.mdx index e6a1cf1b1..c3fa6092a 100644 --- a/docs/en-US/platform/openapi/reference/files/upload-translations.mdx +++ b/docs/en-US/platform/openapi/reference/files/upload-translations.mdx @@ -1,140 +1,21 @@ --- -title: Upload translations -description: Upload translated files to a General Translation Project that match previously uploaded source files. API reference for Upload translations. - +title: "Upload translated files" +description: "Upload translated files linked to their source files. Max 100 files per request. API reference for Upload translated files." method: POST +full: true +_openapi: + method: POST + route: /v2/project/files/upload-translations + toc: [] + structuredData: + headings: [] + contents: + - content: >- + Upload translated files linked to their source files. Max 100 files + per request. --- -Uploads already-translated files for source files that were uploaded earlier. Each entry pairs a source file reference with one or more translations, up to 100 entries per request. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/files/upload-translations -``` - -**Permission** `project:files:write` · **Rate limit** Medium (120/min) - -Attach existing translations to a Project so they are stored alongside their source. To upload the source files first, use [Upload source files](/docs/platform/openapi/reference/files/upload-source). To translate source files with General Translation instead, see [Queue translations](/docs/platform/openapi/reference/translation/queue). - -## How it works [#how-it-works] - -- Each entry's `source` identifies a source file that must already exist. Source files are matched by `branchId`, `versionId`, and `fileId`; a missing `branchId` resolves to the default branch. If a referenced source file is not found, the request fails with `400`. -- The `source` object is validated the same way as an upload, so `fileId` defaults to a hash of `fileName` and `versionId` defaults to a hash of the content when omitted. -- Each translation's `content` is base64-encoded and decoded server-side; invalid base64 or an oversized file is rejected. -- For `fileFormat: "LOTTIE"`, both source and translation content must be base64-encoded dotLottie (`.lottie`) ZIP files. -- Translations inherit the `fileId`, `versionId`, `branchId`, and `fileName` of their source. Set `transformFormat` to store the translation under a different output file format. -- Uploaded translations are marked completed. If the Project has auto-approval enabled, they are also marked approved. `GTJSON` translations receive per-component review metadata derived from the source object. -- Each source file's locale list is updated to include the uploaded translation locales. Files are published to the CDN when the Project has the CDN enabled, except `LOTTIE`, which remains available through the download endpoints. -- If `sourceLocale` is sent and differs from the Project's current default locale, the Project default locale is updated. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`data`](#data) | Array of source/translation entries (1–100). | `object[]` | No | — | -| `sourceLocale` | Source locale for the uploaded files. | `string` | Yes | Project default locale | - -#### `data` [#data] - -**Type** `object[]` · **Required** - -Each element is `{ "source": { ... }, "translations": [ ... ] }`. - -The `source` object identifies the previously uploaded source file: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `content` | Base64-encoded source content. Max file size applies. | `string` | No | — | -| `fileName` | File name; cannot be empty. | `string` | No | — | -| `fileFormat` | File format identifier (for example, `JSON`, `MDX`, or `LOTTIE`). | `string` | No | — | -| `locale` | Locale of the source content; cannot be empty. | `string` | No | — | -| `dataFormat` | Data format for structured content. | `string` | Yes | — | -| `fileId` | Stable file identifier. | `string` | Yes | Hash of `fileName` | -| `versionId` | Version identifier for this content. | `string` | Yes | Hash of content | -| `branchId` | Branch the source file is attached to. | `string` | Yes | Default branch | -| `formatMetadata` | Extra format-specific metadata. | `object` | Yes | — | - -Each element of `translations` is one translated file. At least one translation is required per entry: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `content` | Base64-encoded translated content. Max file size applies. | `string` | No | — | -| `fileName` | File name; cannot be empty. | `string` | No | — | -| `fileFormat` | File format identifier. | `string` | No | — | -| `locale` | Target locale of the translation; cannot be empty. | `string` | No | — | -| `dataFormat` | Data format for structured content. | `string` | Yes | — | -| `transformFormat` | Output file format to store the translation as. | `string` | Yes | Source file format | - -## Response [#response] - -**Status** `201 Created` - -```json title="Response" -{ - "uploadedFiles": [ - { - "branchId": "br_...", - "fileId": "file_...", - "versionId": "ver_...", - "fileName": "en/common.json", - "locale": "es", - "fileFormat": "JSON", - "dataFormat": "JSON" - } - ], - "count": 1, - "message": "Successfully uploaded 1 translation file(s)" -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, invalid locale/format, decode failure, file too large, or referenced source file not found. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`. | -| `429` | Rate limit exceeded. | -| `503` | Server busy; retry with backoff. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/files/upload-translations \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "sourceLocale": "en", - "data": [ - { - "source": { - "content": "eyJoZWxsbyI6ICJIZWxsbyJ9", - "fileName": "en/common.json", - "fileFormat": "JSON", - "locale": "en" - }, - "translations": [ - { - "content": "eyJoZWxsbyI6ICJIb2xhIn0=", - "fileName": "en/common.json", - "fileFormat": "JSON", - "locale": "es" - } - ] - } - ] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/project/branch-info.mdx b/docs/en-US/platform/openapi/reference/project/branch-info.mdx index 9a3abe66d..df85b6d09 100644 --- a/docs/en-US/platform/openapi/reference/project/branch-info.mdx +++ b/docs/en-US/platform/openapi/reference/project/branch-info.mdx @@ -1,75 +1,21 @@ --- -title: Get branch info -description: Inspect branch metadata and General Translation Project branch state. API reference for Get branch information. - +title: "Get branch information" +description: "Return the Project's default branch and any branches requested by name. API reference for Get branch information." method: POST +full: true +_openapi: + method: POST + route: /v2/project/branches/info + toc: [] + structuredData: + headings: [] + contents: + - content: > + Return the Project's default branch and any branches requested by + name. --- -Returns the Project's default branch and any branches you query by name. Use it to resolve branch names to IDs before other file operations. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/branches/info -``` - -**Permission** `project:files:read` · **Rate limit** Default (200/min) - -Look up branches for a Project. To create a branch, use [Create a branch](/docs/platform/openapi/reference/project/create-branch). - -## How it works [#how-it-works] - -- The default branch is always returned, or `null` when the Project has none. -- `branchNames` filters the returned `branches` list. When it is empty, no named branches are returned. -- Each branch is returned as its `id` and `name`. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `branchNames` | Branch names to look up. | `string[]` | Yes | `[]` | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "branches": [ - { "id": "br_...", "name": "feature-x" } - ], - "defaultBranch": { "id": "br_...", "name": "main" } -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/branches/info \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "branchNames": ["feature-x"] - }' -``` + \ No newline at end of file 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..628063935 100644 --- a/docs/en-US/platform/openapi/reference/project/create-branch.mdx +++ b/docs/en-US/platform/openapi/reference/project/create-branch.mdx @@ -1,73 +1,19 @@ --- -title: Create a branch -description: Create a branch, or rename and confirm the default branch, in a General Translation Project. API reference for Create a branch. - +title: "Create a branch" +description: "Create a new branch, or rename and confirm the default branch. API reference for Create a branch." method: POST +full: true +_openapi: + method: POST + route: /v2/project/branches/create + toc: [] + structuredData: + headings: [] + contents: + - content: Create a new branch, or rename and confirm the default branch. --- -Creates a branch in a Project, or confirms and renames the default branch. Returns the resulting branch's ID and name. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/branches/create -``` - -**Permission** `project:files:write` · **Rate limit** Default (200/min) - -Set up a branch before uploading files to it. To look up existing branches, use [Get branch information](/docs/platform/openapi/reference/project/branch-info). - -## 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`. -- Otherwise the branch is created (or reused if it already exists) and returned as its `id` and `name`. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `branchName` | Name of the branch; cannot be empty. | `string` | No | — | -| `defaultBranch` | Treat this as the Project's default branch. | `boolean` | Yes | `false` | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "branch": { "id": "br_...", "name": "feature-x" } -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, or empty `branchName`. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`, or the free plan does not allow non-default branches. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/branches/create \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "branchName": "feature-x" - }' -``` + \ No newline at end of file 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..2bc988e11 --- /dev/null +++ b/docs/en-US/platform/openapi/reference/project/create-project.mdx @@ -0,0 +1,23 @@ +--- + +title: "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. Enabling CDN delivery also requires project:write. API reference for Create a project." +method: POST +full: true +_openapi: + method: POST + route: /v2/projects + toc: [] + structuredData: + headings: [] + contents: + - content: > + 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. Enabling CDN delivery also + requires `project:write`. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + + \ No newline at end of file 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", diff --git a/docs/en-US/platform/openapi/reference/project/project-info.mdx b/docs/en-US/platform/openapi/reference/project/project-info.mdx index 022bedfb3..1e838c24f 100644 --- a/docs/en-US/platform/openapi/reference/project/project-info.mdx +++ b/docs/en-US/platform/openapi/reference/project/project-info.mdx @@ -1,70 +1,21 @@ --- -title: Get Project info -description: Read General Translation Project metadata, settings, and configuration details. API reference for Get Project information. - +title: "Get project information" +description: "Read the authenticated Project's name, Organization ID, locale settings, and auto-approval setting. API reference for Get project information." method: GET +full: true +_openapi: + method: GET + route: /v2/project/info/{projectId} + toc: [] + structuredData: + headings: [] + contents: + - content: > + Read the authenticated Project's name, Organization ID, locale + settings, and auto-approval setting. --- -Returns core metadata and locale settings for a Project. The Project ID in the path must match the authenticated Project. - -## Overview [#overview] - -```http -GET https://api2.gtx.dev/v2/project/info/:projectId -``` - -**Permission** `project:files:read` · **Rate limit** Default (200/min) - -Read a Project's name, locales, and settings. To change the default locale, use [Update Project information](/docs/platform/openapi/reference/project/update-project). - -## How it works [#how-it-works] - -- The `projectId` in the path must match the Project the API key is authenticated for. A missing or mismatched ID returns `400`. -- The response includes the Project's name, Organization ID, default and current locales, and whether auto-approval is enabled. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Path parameters - -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| `projectId` | Project ID; must match the authenticated Project. | `string` | Yes | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "id": "prj_...", - "name": "My Project", - "orgId": "org_...", - "defaultLocale": "en", - "currentLocales": ["es", "fr"], - "autoApprove": false -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Missing `projectId`, or it does not match the authenticated Project. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X GET https://api2.gtx.dev/v2/project/info/prj_... \ - -H "x-gt-api-key: gtx-api-..." -``` + \ No newline at end of file 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..060f4041f 100644 --- a/docs/en-US/platform/openapi/reference/project/update-project.mdx +++ b/docs/en-US/platform/openapi/reference/project/update-project.mdx @@ -1,78 +1,19 @@ --- -title: Update Project info -description: Update General Translation Project-level settings from automation. API reference for Update Project information. - +title: "Update project information" +description: "Update the project's default locale or CDN delivery setting. API reference for Update project information." method: POST +full: true +_openapi: + method: POST + route: /v2/project/info/{projectId} + toc: [] + structuredData: + headings: [] + contents: + - content: Update the project's default locale or CDN delivery setting. --- -Updates Project-level settings such as the default locale. The Project ID in the path must match the authenticated Project. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/info/:projectId -``` - -**Permission** `project:write` · **Rate limit** Default (200/min) - -Change a Project's settings from your own automation. To read the current settings, use [Get Project information](/docs/platform/openapi/reference/project/project-info). - -## How it works [#how-it-works] - -- 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. -- The response confirms success. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Path parameters - -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| `projectId` | Project ID; must match the authenticated Project. | `string` | Yes | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `defaultLocale` | New default locale for the Project. | `string` | Yes | Unchanged | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "success": true -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Missing or mismatched `projectId`, or an invalid `defaultLocale`. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:write`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -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" - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/project/upload-assets.mdx b/docs/en-US/platform/openapi/reference/project/upload-assets.mdx index 9f703ca87..03f99fe02 100644 --- a/docs/en-US/platform/openapi/reference/project/upload-assets.mdx +++ b/docs/en-US/platform/openapi/reference/project/upload-assets.mdx @@ -1,114 +1,26 @@ --- -title: Upload Project assets -description: Upload font assets for General Translation Lottie workflows in an Organization. API reference for Upload Project assets. - +title: "Upload project assets" +description: "Upload OpenType or TrueType fonts through a project and make them available to Lottie translation workflows across its organization. Each font is keyed by a normalized identity derived from its family, weight, and italic style (from the supplied family and style, or from the font metadata and file name). Re-uploading the same identity overwrites the existing asset, so complete retries after a 500 response are safe. API reference for Upload project assets." method: POST - +full: true +_openapi: + method: POST + route: /v2/project/assets + toc: [] + structuredData: + headings: [] + contents: + - content: > + Upload OpenType or TrueType fonts through a project and make them + available to Lottie translation workflows across its organization. + Each font is keyed by a normalized identity derived from its family, + weight, and italic style (from the supplied `family` and `style`, or + from the font metadata and file name). Re-uploading the same identity + overwrites the existing asset, so complete retries after a `500` + response are safe. --- -Uploads OpenType or TrueType fonts through a Project and makes them available to Lottie translation workflows across its Organization. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/assets -``` - -**Permission** `project:files:write` · **Rate limit** Medium (120/min) - -## How it works [#how-it-works] - -- Each request accepts one to 50 fonts. -- Each font must be valid base64, use a `.ttf` or `.otf` file name, and decode to no more than 20MB. -- The Project determines which Organization owns the assets. Uploaded fonts persist across that Organization's translation jobs. -- Each font is keyed by a normalized identity made from its family, weight, and italic style. The server uses the supplied `family` and `style`, or derives them from the font metadata and then the file name. -- Re-uploading the same font identity overwrites the existing asset, even when the bytes or file name change. -- Correct `400` input errors before retrying. A complete retry after a `500` response is safe because each font identity is upserted. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`assets`](#assets) | Font assets to upload (1–50). | `object[]` | No | — | - -#### `assets` - -**Type** `object[]` · **Required** - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `assetType` | Asset type. Only `FONT` is supported. | `'FONT'` | No | — | -| `content` | Base64-encoded font content, up to 20MB after decoding. | `string` | No | — | -| `fileName` | Font file name ending in `.ttf` or `.otf` (1–255 characters). | `string` | No | — | -| `family` | Font family name used by the Lottie file. When omitted, the server derives it from the font or file name. | `string` | Yes | Derived | -| `style` | Style or weight used with `family`, such as `Bold`, `350`, or `Bold Italic`. Ignored when `family` is omitted. | `string` | Yes | Regular (`400`) when `family` is set | - -## Response [#response] - -**Status** `201 Created` - -| Field | Description | Type | -| --- | --- | --- | -| `assets` | Uploaded font assets. | `object[]` | -| `assets[].id` | Stored Organization asset ID. | `string` | -| `assets[].assetKey` | Normalized identity in the form `-[-i]`. | `string` | -| `assets[].fileName` | File name from the request. | `string` | -| `count` | Number of uploaded assets. | `number` | - -```json title="Response" -{ - "assets": [ - { - "id": "asset_...", - "assetKey": "brandsans-700", - "fileName": "BrandSans.ttf" - } - ], - "count": 1 -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, invalid base64, an empty asset, an unsupported file extension, an asset larger than 20MB, or a font family that cannot be determined. Provide `family` when identity cannot be derived; `style` remains optional and defaults to `400`. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`. | -| `404` | Project not found. | -| `413` | JSON request body exceeds 100MB. | -| `429` | Rate limit exceeded. | -| `500` | An asset could not be stored. Retry the complete request. | - -## Example [#example] - -```bash -FONT_BASE64=$(base64 < ./BrandSans.ttf | tr -d '\n') +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -curl -X POST https://api2.gtx.dev/v2/project/assets \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d "{ - \"assets\": [ - { - \"assetType\": \"FONT\", - \"content\": \"$FONT_BASE64\", - \"fileName\": \"BrandSans.ttf\", - \"family\": \"Brand Sans\", - \"style\": \"Bold\" - } - ] - }" -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/project/upsert-tag.mdx b/docs/en-US/platform/openapi/reference/project/upsert-tag.mdx index 95326599d..b8001263c 100644 --- a/docs/en-US/platform/openapi/reference/project/upsert-tag.mdx +++ b/docs/en-US/platform/openapi/reference/project/upsert-tag.mdx @@ -1,100 +1,19 @@ --- -title: Create or update tag -description: Create or update a tag on General Translation file versions for release tracking. API reference for Create or update tag. - +title: "Create or update a tag" +description: "Create or upsert a tag that points at a set of file versions. API reference for Create or update a tag." method: POST +full: true +_openapi: + method: POST + route: /v2/project/tags/create + toc: [] + structuredData: + headings: [] + contents: + - content: Create or upsert a tag that points at a set of file versions. --- -Creates a tag on a set of file versions, or overwrites an existing tag with the same ID. Use tags to mark the file versions that belong to a release. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/tags/create -``` - -**Permission** `project:files:write` · **Rate limit** Default (200/min) - -Pin a named tag to specific file versions. To resolve the file references first, use [Get file information](/docs/platform/openapi/reference/files/file-info). - -## How it works [#how-it-works] - -- Each file reference (`fileId` + `versionId` + `branchId`) is resolved to an internal source file. An existing tag with the same `tagId` is overwritten. -- If none of the references resolve to a source file, the request returns `400`. If some references resolve and others do not, the request returns `400` and lists the unresolved file IDs. -- The response returns the stored tag, including its timestamps. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `tagId` | Tag identifier (1–255 characters). | `string` | No | — | -| [`files`](#files) | File versions to tag; at least one required. | `object[]` | No | — | -| `message` | Optional message for the tag (max 255 characters). | `string` | Yes | — | - -#### `files` [#files] - -**Type** `object[]` · **Required** - -Each element references one file version. All values cannot be blank: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `fileId` | Stable file identifier. | `string` | No | — | -| `versionId` | Version identifier. | `string` | No | — | -| `branchId` | Branch the file is attached to. | `string` | No | — | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "tag": { - "id": "tag_...", - "tagId": "v1.2.0", - "message": "Release 1.2.0", - "createdAt": "2026-01-01T00:00:00.000Z", - "updatedAt": "2026-01-01T00:00:00.000Z" - } -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, no matching source files, or some file references could not be resolved. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:write`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/tags/create \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "tagId": "v1.2.0", - "message": "Release 1.2.0", - "files": [ - { - "fileId": "file_...", - "versionId": "ver_...", - "branchId": "br_..." - } - ] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/translation/job-status.mdx b/docs/en-US/platform/openapi/reference/translation/job-status.mdx index 4dec475b3..3a0ec0caa 100644 --- a/docs/en-US/platform/openapi/reference/translation/job-status.mdx +++ b/docs/en-US/platform/openapi/reference/translation/job-status.mdx @@ -1,80 +1,21 @@ --- -title: Get translation job status -description: Retrieve status for a queued translation job in General Translation. API reference for Get translation job status. - +title: "Get translation job status" +description: "Return normalized status information for one or more queued translation or context generation jobs. API reference for Get translation job status." method: POST +full: true +_openapi: + method: POST + route: /v2/project/jobs/info + toc: [] + structuredData: + headings: [] + contents: + - content: > + Return normalized status information for one or more queued + translation or context generation jobs. --- -Returns the status of one or more queued jobs by ID. Use it to poll jobs created by [Queue translations](/docs/platform/openapi/reference/translation/queue) or [Generate translation context](/docs/platform/openapi/reference/context/generate-context). - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/jobs/info -``` - -**Permission** `project:files:read` · **Rate limit** Default (200/min) - -Check the progress of background jobs in one request. - -## How it works [#how-it-works] - -- Send one or more job IDs. Jobs are looked up within the authenticated Project. -- Each job's raw status is normalized: pending and queued jobs report `queued`; processing and retrying jobs report `processing`; failed jobs report `failed` with an `error.message`; completed jobs report `completed`. -- Only jobs that match the provided IDs are returned. IDs that do not resolve to a job are omitted from the response array; a request whose IDs match nothing returns `200` with an empty array. - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `jobIds` | Job IDs to look up; at least one required, each cannot be blank. | `string[]` | No | — | - -## Response [#response] - -**Status** `200 OK` - -The response is a JSON array with one entry per resolved job: - -```json title="Response" -[ - { "status": "completed", "jobId": "job_a..." }, - { "status": "processing", "jobId": "job_b..." }, - { - "status": "failed", - "jobId": "job_c...", - "error": { "message": "Translation failed" } - } -] -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, or an empty `jobIds` array. | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:files:read`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/jobs/info \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "jobIds": ["job_a...", "job_b..."] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/translation/queue.mdx b/docs/en-US/platform/openapi/reference/translation/queue.mdx index ca7dde5d7..66e70dce6 100644 --- a/docs/en-US/platform/openapi/reference/translation/queue.mdx +++ b/docs/en-US/platform/openapi/reference/translation/queue.mdx @@ -1,110 +1,22 @@ --- -title: Queue translations -description: Queue uploaded source files for background translation in a General Translation Project. API reference for Queue translations. - +title: "Queue files for translation" +description: "Enqueue uploaded source files for background translation. Max 100 files per request. The response shape depends on the requested gt-api-version. API reference for Queue files for translation." method: POST +full: true +_openapi: + method: POST + route: /v2/project/translations/enqueue + toc: [] + structuredData: + headings: [] + contents: + - content: > + Enqueue uploaded source files for background translation. Max 100 + files per request. The response shape depends on the requested + `gt-api-version`. --- -Enqueues background translation jobs for source files that were already uploaded. Reference up to 100 files and the target locales to translate them into. - -## Overview [#overview] - -```http -POST https://api2.gtx.dev/v2/project/translations/enqueue -``` - -**Permission** `project:translations:enqueue` · **Rate limit** Heavy (30/min) - -Start background translation of uploaded files. Upload the files first with [Upload source files](/docs/platform/openapi/reference/files/upload-source), then track the resulting jobs with [Get translation job status](/docs/platform/openapi/reference/translation/job-status). - -## How it works [#how-it-works] - -- Each referenced source file must already exist. Missing source files are reported in a `400` response with a `missing` list and a `count`. -- A missing `branchId` resolves to the default branch. Set `transformFormat` to translate a file into a different output file format. -- When `targetLocales` is omitted, the Project's configured locales are used. Files already translated into a locale are skipped unless `force` is `true`. -- The response shape depends on the API version sent via the `gt-api-version` header. Version `2025-11-03.v1` and later return `jobData` keyed by job. See [versioning in the Overview](/docs/platform/openapi/overview#api-basics). - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`files`](#files) | Source files to translate (1–100). | `object[]` | No | — | -| `targetLocales` | Locales to translate into. | `string[]` | Yes | Project locales | -| `sourceLocale` | Source locale of the files. | `string` | Yes | Project default locale | -| `force` | Re-translate files that already have translations. | `boolean` | Yes | `false` | -| `modelProvider` | Model provider to use for translation. | `string` | Yes | — | -| `publish` | Publish the resulting translations to the CDN. | `boolean` | Yes | — | - -#### `files` [#files] - -**Type** `object[]` · **Required** - -Each element references one uploaded source file: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `fileId` | Stable file identifier; required. | `string` | No | — | -| `versionId` | Version identifier; required. | `string` | No | — | -| `branchId` | Branch the file is attached to. | `string` | Yes | Default branch | -| `fileName` | File name. | `string` | Yes | — | -| `transformFormat` | Output file format to translate into. | `string` | Yes | Source file format | - -## Response [#response] - -**Status** `200 OK` - -```json title="Response" -{ - "jobData": { - "job_...": { - "sourceFileId": "sf_...", - "fileId": "file_...", - "versionId": "ver_...", - "branchId": "br_...", - "targetLocale": "es", - "projectId": "prj_...", - "force": false - } - }, - "locales": ["es", "fr"], - "message": "Enqueued 2 translation(s)." -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, invalid locale, or referenced source files not found (returned with `missing` and `count`). | -| `401` | Missing or invalid API key. | -| `403` | API key lacks `project:translations:enqueue`. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://api2.gtx.dev/v2/project/translations/enqueue \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "files": [ - { - "fileId": "file_...", - "versionId": "ver_..." - } - ], - "targetLocales": ["es", "fr"] - }' -``` + \ No newline at end of file diff --git a/docs/en-US/platform/openapi/reference/translation/translate-runtime.mdx b/docs/en-US/platform/openapi/reference/translation/translate-runtime.mdx index 9774ead41..36fcc1c21 100644 --- a/docs/en-US/platform/openapi/reference/translation/translate-runtime.mdx +++ b/docs/en-US/platform/openapi/reference/translation/translate-runtime.mdx @@ -1,115 +1,22 @@ --- -title: Translate at runtime -description: Translate strings or structured content directly from an application or service with General Translation. API reference for Translate content at runtime. - +title: "Translate content at runtime" +description: "Translate one or more strings or structured content entries with caching and memoization. Authentication is optional; unauthenticated requests may receive partial results. API reference for Translate content at runtime." method: POST +full: true +_openapi: + method: POST + route: /v2/translate + toc: [] + structuredData: + headings: [] + contents: + - content: > + Translate one or more strings or structured content entries with + caching and memoization. Authentication is optional; unauthenticated + requests may receive partial results. --- -Translates a batch of keyed requests into a single target locale and returns the translations in the response. General Translation uses a cache-first path so repeat requests are fast and inexpensive. - -## Overview [#overview] - -```http -POST https://runtime2.gtx.dev/v2/translate -``` - -**Permission** `project:translations:generate` · **Rate limit** Default (200/min) - -Translate content on demand from your own application or service. This endpoint uses the runtime base URL `https://runtime2.gtx.dev`. To translate whole files in the background instead, use [Queue translations](/docs/platform/openapi/reference/translation/queue). - -## How it works [#how-it-works] - -- Requests are a map of your own keys to source content. Each request is resolved independently, and results are keyed by the same keys. -- The service checks its memoized cache first, then in-progress translations, and finally completes any remaining translations before returning. Newly completed translations are written back to the cache. -- Each request's `dataFormat` selects how its `source` is parsed: `STRING` (default), `JSX`, `ICU`, or `I18NEXT`. -- Setting `metadata.modelProvider` requires an Enterprise plan; otherwise the request returns `403`. -- Target locales are enforced against the Project's allowed locales. -- A successful response is `201` (or `200` when every request was served from cache). - -## Request [#request] - -### Headers - -| Header | Description | Required | -| --- | --- | --- | -| `x-gt-api-key` | Project or Organization API key. | Yes | -| `x-gt-project-id` | Project ID. Required when using an Organization key. | No | - -### Body - -**Content type** `application/json` - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| [`requests`](#requests) | Map of request key to content to translate; at least one required. | `object` | No | — | -| `targetLocale` | Locale to translate into; cannot be empty. | `string` | No | — | -| `sourceLocale` | Locale of the source content; cannot be empty. | `string` | No | — | -| `metadata` | Metadata shared by all requests. | `object` | Yes | — | - -The shared `metadata` object accepts `modelProvider` (an allowed model provider identifier; Enterprise only). - -#### `requests` [#requests] - -**Type** `object` · **Required** - -Each value is a single translation request: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `source` | Source content to translate. Shape depends on `metadata.dataFormat`. | `unknown` | No | — | -| `metadata` | Per-request metadata. | `object` | Yes | See below | - -Per-request `metadata` fields: - -| Field | Description | Type | Optional | Default | -| --- | --- | --- | --- | --- | -| `dataFormat` | Content format: `STRING`, `JSX`, `ICU`, or `I18NEXT`. | `string` | Yes | `STRING` | -| `context` | Extra context to guide the translation. | `string` | Yes | — | -| `id` | Caller-supplied identifier for the entry. | `string` | Yes | — | -| `hash` | Content hash; computed server-side when omitted. | `string` | Yes | — | -| `maxChars` | Maximum character length for the translation. | `number` | Yes | — | -| `actionType` | Translation action type. | `string` | Yes | `fast` | -| `sourceCode` | Surrounding source-code snippets for additional context. | `object` | Yes | — | - -## Response [#response] - -**Status** `201 Created` - -Each entry is keyed by its request key. Successful entries include the translation; failed entries include an error and code. - -```json title="Response" -{ - "key1": { - "success": true, - "translation": "Hola, mundo", - "dataFormat": "STRING", - "locale": "es" - } -} -``` - -## Errors [#errors] - -| Status | Cause | -| --- | --- | -| `400` | Invalid request body, or invalid source/target locale. | -| `401` | Missing or invalid API key. | -| `402` | Token quota exhausted or the request cannot be billed. | -| `403` | API key lacks `project:translations:generate`, or a custom `modelProvider` requires an Enterprise plan. | -| `429` | Rate limit exceeded. | - -## Example [#example] +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} -```bash -curl -X POST https://runtime2.gtx.dev/v2/translate \ - -H "x-gt-api-key: gtx-api-..." \ - -H "Content-Type: application/json" \ - -d '{ - "requests": { - "key1": { "source": "Hello, world" } - }, - "sourceLocale": "en", - "targetLocale": "es" - }' -``` + \ No newline at end of file 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/(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/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/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/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/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 14c58e595..2709212f8 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 d8dcb9de6..86bdef132 100644 --- a/docs/en-US/react/overview.mdx +++ b/docs/en-US/react/overview.mdx @@ -1,35 +1,35 @@ --- 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 which React library and quickstart fit 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'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, but all of them expose the same translation API: +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 and not yet recommended for production.* +*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 package is built on the same core, you learn the model once and reuse it everywhere. The pieces are: +Because every React i18n library shares the same core components and hooks, there is one translation model 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), 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/reference/components/branch.mdx b/docs/en-US/react/reference/components/branch.mdx index 8c09c170a..ef85f0d13 100644 --- a/docs/en-US/react/reference/components/branch.mdx +++ b/docs/en-US/react/reference/components/branch.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 0e0ade9ee..94a70fdb2 100644 --- a/docs/en-US/react/reference/components/currency.mdx +++ b/docs/en-US/react/reference/components/currency.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 114a5b2e0..b0da6220a 100644 --- a/docs/en-US/react/reference/components/datetime.mdx +++ b/docs/en-US/react/reference/components/datetime.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 5bb3f9d10..f900f5ee4 100644 --- a/docs/en-US/react/reference/components/derive.mdx +++ b/docs/en-US/react/reference/components/derive.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 707e5866a..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: GTProvider -description: Provide the active locale and translations to a General Translation gt-react component tree. API reference for GTProvider. +title: "" +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 872d051fd..b51a6e2fe 100644 --- a/docs/en-US/react/reference/components/locale-selector.mdx +++ b/docs/en-US/react/reference/components/locale-selector.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 785cca170..ee5914e59 100644 --- a/docs/en-US/react/reference/components/num.mdx +++ b/docs/en-US/react/reference/components/num.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 e837001b4..434a560e6 100644 --- a/docs/en-US/react/reference/components/plural.mdx +++ b/docs/en-US/react/reference/components/plural.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 ec1e5a29f..55942212e 100644 --- a/docs/en-US/react/reference/components/region-selector.mdx +++ b/docs/en-US/react/reference/components/region-selector.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 268397711..7edfd0271 100644 --- a/docs/en-US/react/reference/components/relative-time.mdx +++ b/docs/en-US/react/reference/components/relative-time.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 dbb598666..20f83de79 100644 --- a/docs/en-US/react/reference/components/t.mdx +++ b/docs/en-US/react/reference/components/t.mdx @@ -1,13 +1,13 @@ --- -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. --- 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 3c81be250..ddcb4201f 100644 --- a/docs/en-US/react/reference/components/var.mdx +++ b/docs/en-US/react/reference/components/var.mdx @@ -1,13 +1,13 @@ --- -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. --- 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/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..7989e1096 100644 --- a/docs/en-US/react/reference/functions/declare-var.mdx +++ b/docs/en-US/react/reference/functions/declare-var.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 7e99fd80f..9f29caf96 100644 --- a/docs/en-US/react/reference/functions/decode-vars.mdx +++ b/docs/en-US/react/reference/functions/decode-vars.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 9c4cb27fa..c584da6bf 100644 --- a/docs/en-US/react/reference/functions/derive.mdx +++ b/docs/en-US/react/reference/functions/derive.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 8ead863ae..75ecb2bfb 100644 --- a/docs/en-US/react/reference/functions/get-translations-snapshot.mdx +++ b/docs/en-US/react/reference/functions/get-translations-snapshot.mdx @@ -1,13 +1,13 @@ --- 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. --- 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/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..44e8b7f27 100644 --- a/docs/en-US/react/reference/functions/msg.mdx +++ b/docs/en-US/react/reference/functions/msg.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 da5d9e237..2813d85c8 100644 --- a/docs/en-US/react/reference/functions/t-function.mdx +++ b/docs/en-US/react/reference/functions/t-function.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 24b32fd93..7dcf4947e 100644 --- a/docs/en-US/react/reference/hooks/use-default-locale.mdx +++ b/docs/en-US/react/reference/hooks/use-default-locale.mdx @@ -1,18 +1,20 @@ --- 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. --- 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 6ee214719..68337ce6e 100644 --- a/docs/en-US/react/reference/hooks/use-gt.mdx +++ b/docs/en-US/react/reference/hooks/use-gt.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 2a7dd8ad2..789e83fca 100644 --- a/docs/en-US/react/reference/hooks/use-locale-direction.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-direction.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 742abb52a..1a5c6e8fa 100644 --- a/docs/en-US/react/reference/hooks/use-locale-properties.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-properties.mdx @@ -1,13 +1,13 @@ --- 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. --- 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 885dfab08..2e2f03467 100644 --- a/docs/en-US/react/reference/hooks/use-locale-selector.mdx +++ b/docs/en-US/react/reference/hooks/use-locale-selector.mdx @@ -1,18 +1,20 @@ --- 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. --- 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 `