Repository navigation
docs(kb): revise the five original articles for answer engines - #650
Conversation
Applies the #630 revisions to the articles already on main: - kb/best-localization-software.mdx - kb/how-to-handle-plurals-in-react.mdx - kb/i18n-without-translation-files.mdx - kb/multilingual-nextjs-seo.mdx - kb/translate-conditional-jsx.mdx Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Answer first in the summary and body, with question headings that each answer one query: categories per language (English, Japanese, Russian, Polish, Arabic), the General Translation <Plural> steps, an English-only Intl.PluralRules helper, ICU plurals with useGT, how react-i18next and react-intl store forms, a decision table, and common questions on zero, Next.js, and which counts to test. Fix the CLDR expansion to Common Locale Data Repository and drop the Google Translate and raw AI API rows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Answer the title in the first sentence of the summary and the body, with General Translation, gt-react and gt-next named in the sentence that makes the claim. Give each of the article's ten tracked queries a section whose heading is the question and whose first sentence answers it: inline vs key files with a react-i18next and gt-next checkout example, which libraries take inline JSX (Lingui and next-intl extraction rows, General Translation last), pros and cons of keys vs inline, Next.js App Router setup steps, keeping generated JSON in sync, automatic i18n (compiler JSX injection and Locadex), and gt-next vs next-intl. Keep Jackie's review, context, CDN and local delivery, account, pricing and migration content, and drop the Django row and the unverified ICU sentence. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Split the article into question sections (one language indexed, URL structure, routing, html lang, hreflang and canonical, translated metadata, sitemap, library comparison) and restore working code for generateMetadata alternates with x-default and app/sitemap.ts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Split the hreflang answer into its own short paragraph, put General Translation in the sentences that carry claims about gt-next, and lead the URL structure section with Google's source. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Restores the key-count arithmetic from the original (500 keys in 10 languages is 5,000 entries) as an answer to whether paid localization software is worth it or JSON locale files can be kept by hand. Splits the long sections into question headings, one kind of question each: choosing software, the approach table, the cost of maintaining JSON files, when a translation management system fits, when a developer-first tool fits, Google Translate or an AI API, and how General Translation translates, adds context, delivers, keeps current, and supports review. Adds Key takeaways. Names no localization companies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nslate-conditional-jsx Adds two self-contained question sections: - How do I translate a sentence with a variable and a link in React? Direct answer, an approach table (separate strings, react-i18next Trans, react-intl FormattedMessage, General Translation last), a use-when paragraph, and a gt-react <T> with <Var> and an inline <a>, plus the static-jsx auto-wrap and gt-next/link for the App Router. - How do react-i18next's Trans and General Translation's T handle nested elements? Indexed tags (<3></3>), the default named basic tags, the components prop, react-intl's named tags, why nesting breaks, and how <T> handles nested elements with the <T> reference example. Bumps updated to 2026-10-16. Other frontmatter unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds the new articles from #630: - kb/add-i18n-to-nextjs.mdx - kb/ai-agent-i18n-setup.mdx - kb/format-numbers-dates-currencies.mdx - kb/review-translations.mdx - kb/translate-google-slides.mdx - kb/translate-mintlify-docs.mdx - kb/translate-node-app.mdx - kb/translate-react-app.mdx - kb/translate-react-native-app.mdx - kb/translate-sanity-content.mdx - kb/translate-storyblok-content.mdx - kb/translate-strings-outside-jsx.mdx - kb/translate-vue-app.mdx - kb/translations-in-ci.mdx - kb/what-is-locadex.mdx validate-kb.ts accepts an optional updated date (a real date from date to today), which the new articles set, and test-validate-kb.ts covers it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Kevin, a few changes we'd like before publishing, primarily in
The clearer answers and practical examples are welcome. Please retain the central commercial argument that GT brings the libraries, translation, context, and ongoing maintenance together. |
- translations-in-ci: cut the unsourced Ramp figure, and say that --publish sends results to the CDN instead of the codebase. - add-i18n-to-nextjs: drop the unsourced "direct input from Vercel". - translate-google-slides: replace the widget's width percentages with a sourced general statement, and drop the unsourced claim that the .pptx round trip turns charts and videos into images. - translate-mintlify-docs: describe the Hide default locale in URL paths toggle, which is on by default and keeps source paths unchanged. - review-translations and what-is-locadex: Dashboard edits reach GitHub through the next Locadex translation run, not a pull request per edit. - what-is-locadex: open with the direct answer and the approach table, state the plan requirement once, and link the pricing page. - All 15 articles: set date to 2026-10-21 and drop updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Storyblok's own docs now place languages under Settings > Internationalization and personal access tokens under My account > Account settings > Personal access tokens. Update the Quickstart, the configuration guide and both reference pages to match, so they agree with the Storyblok knowledge base article. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in the review fixes to the 15 new articles and the Storyblok docs. The merge has no conflicts: this branch changes only the five original articles, and the base branch changes none of them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lization-software - Add a pricing section: usage-based billing with no seat fees, the Starter plan's $0 platform fee and unlimited users, the free allowance, and the current usage rates, checked against the pricing and usage rates pages and the billing docs. - Replace the broad advice to pick a translation management system with the specific requirements another product meets, each from that product's own docs: Phrase for XLIFF and Office files, Lokalise for over-the-air updates in native apps, Weblate and Tolgee for self-hosting, Transifex Live for snippet-based website translation, and Crowdin's free open-source license. Apply the same specifics to the choosing guide, the approach summary and the takeaways. - Lead the Locadex section with what each automation can be set to do: when it runs, what it changes, and how its changes reach GitHub, and leave the defaults to the configuration guide. - Cut the unsourced Ramp speed figure, as in the new articles. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks, Jackie. All three are in 72cc20b, on top of a merge of #649's branch (f04a880), which brings in the review fixes there and had no conflicts. 1. Pricing section. "How much does General Translation cost?" is back as its own section. It covers usage-based billing with no seat fees, Starter's $0 platform fee with unlimited users, projects and languages, what Enterprise adds, the free allowance (5M credits, or $5 of usage, per rolling 30 days), and a table of the current rates: $1 per 1,000 input tokens for build-time translation ($2 for GT Content Files), $0.40 for runtime and development translation, $0.02 per 1,000 input tokens per 1,000 context tokens for Platform Context, $0.50 per Google Slides slide, $5 per LCU, and $0 per CDN request. It ends with the usage page's own example ($1.06 for a 1,000-token Markdown file with 3,000 context tokens) and a link to the pricing page. Every number comes from the pricing and usage rates pages and the billing docs. 2. Specific reasons to choose another product. The TMS section is now "When is another localization product a better fit?", with one requirement per product, each cited to that product's own docs:
Each item says what General Translation does instead. The "separate localization team" and "content outside the codebase" reasons are gone. The choosing guide, the summary under the table, the TMS row (which now names Phrase, Lokalise and Crowdin) and the takeaways use the same specifics. The Google Translate and AI API advice is narrower too: Google Translate for translating one uploaded document, and the AI APIs when translation is one step in a model call your own product makes. 4. Locadex customization. The Locadex part now opens with what an automation can be set to do:
The "off by default" sentence is gone, and the defaults are left to the linked configuration guide. I kept the central argument, the answers and the examples. I also cut the Ramp speed figure, the same unsourced claim Kevin Wu flagged in #649, and set Update: the remaining conflict with main is resolved in 1ca4283; see the comment below. |
Main now keeps the knowledge base in kb/en-US/ (#671) and requires a short description when a summary is too long for a meta description (#662). The merge has no textual conflicts. The validator tests this branch added for `updated` now expect kb/en-US/ paths, to match the rest of main's tests. The 15 new articles move in the next commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Follows #671, which keeps the English knowledge base source in kb/en-US/. Renames only; the content is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each summary is longer than the 200-character meta description limit that main's validator now enforces (#662), so each article gets a description of 200 characters or fewer that answers its question on its own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in main by way of #649's branch: the knowledge base now lives in kb/en-US/ (#671), and every article has a meta description (#662). The five revised articles move to kb/en-US/ with their revised bodies and summaries. Each frontmatter conflict keeps this branch's summary and takes main's description line, rewritten to match the revised summary. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The revisions publish with this PR, so an updated date of 2026-10-16 would show an older "Last updated" than the publish date, the issue raised in review on #649. best-localization-software already has 2026-10-21. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Synced with main through #649's branch in 1ca4283, which clears the conflict. Following #671, the five revised articles are now in |
ai-agent-i18n-setup said Locadex automation "is available across accounts". Locadex workflows require a Starter or Enterprise plan (locadex_workflows in packages/node/src/auth/features.ts), so the sentence now states the plan requirement and links the usage rates. The same article offered "unlimited seats" without the plan. Team invites also require Starter or Enterprise, so it now says both plans include unlimited users, and names the Enterprise feature it means: translation approval. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in the plan and billing fix to ai-agent-i18n-setup. The merge has no conflicts: this branch changes only the five original articles. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
translate-conditional-jsx said gt-next's Link turns /terms into /en/terms for an English visitor. Link leaves the default locale unprefixed unless prefixDefaultLocale is set, so the example now uses a Spanish visitor and /es/terms. multilingual-nextjs-seo said Profound's main product is a Next.js App Router app, which no public page states. It now uses the figure the enterprise page publishes, 47+ locales across platform and docs, in the same form as the other knowledge base articles. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve the conflict in kb/en-US/multilingual-nextjs-seo.mdx between #650's answer-engine rewrite on main and this branch's rewrite plus #679. - Keep #650's question headings, requirements table, URL-structure and library comparisons, locale layout with isLocaleSupported, and build script. - Keep #679's published-locales record, noindex with alternates: null, x-default fallback, and rendered head and sitemap output. - Prefix every locale, matching the rest of the KB set, and describe html lang as an accessibility signal rather than a Google language signal. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>



#649 merged on 2026-10-22 as 855a60b, so this PR's base is now
main. Main is merged in at 2a293e0, which takes main's version of #649's 15 articles, so this PR changes only the five original articles.This PR revises the five original knowledge base articles so answer engines pull and cite them more often. Each revision was tested blind against the article on main, and all five win by a wide margin.
Results
Each article was judged 40 times: 10 queries the revisions were never tuned on, both page orders, and two judge models. Judges saw two anonymous, date-stripped copies and picked the passage they would quote for each query.
how-to-handle-plurals-in-reactmultilingual-nextjs-seoi18n-without-translation-filesbest-localization-softwaretranslate-conditional-jsxThe last two rows are from a second blind round on a fresh query set, after those two articles were strengthened. A keyword retrieval check (BM25) agrees: the revision holds the best-matching passage for most queries.
#630's own edits cleared this bar for two of the five. Three needed another pass:
how-to-handle-plurals-in-react,multilingual-nextjs-seoandi18n-without-translation-fileswere rewritten so each section answers one real question on its own and names General Translation in the sentence that makes the claim.best-localization-softwaregets back the original's arithmetic on what hand-maintained JSON files cost, and its long sections are split into single-question passages.translate-conditional-jsxadds a variable and a link inside one translated sentence, and how nested elements work with react-i18next'sTranscompared with<T>.Every fact was checked against
docs/en-US.After review,
best-localization-softwaregained a pricing section checked against the pricing and usage rates pages, names the products that fit specific requirements better (Phrase, Lokalise, Weblate, Tolgee, Transifex and Crowdin, each cited to its own docs), and leads its Locadex section with the automation settings. The blind-test numbers above are for the revision before those changes.Main's changes
#641 edited four of these articles after #630 began. The revisions already drop the passages it corrected (the "Sub-50ms" line, the Spanish, German and Italian number note, the React
LocaleSelectorimport and the Dark Mode snippet), so the rebase keeps the tested text. The Next.js example importsLocaleSelectorfromgt-next, as the Next.js quickstart does.Checks
All content validators pass on this branch (
npm test, the sixvalidate:*scripts,typecheck,validate-links.ts).🤖 Generated with Claude Code
KB editorial audit — October 19: Inherited the Locadex setup revision from #649. The no-translation-files article now describes the supported webpack compiler path and explicit wrappers for Turbopack directly. KB, internal-link, reference-link, and unsafe-HTML validation pass. Engineering defect evidence stays outside published KB prose; the NestJS scanner reproduction is tracked in generaltranslation/gt#2474. This audit does not merge or publish the articles.
Follow-up fixes
6b46073 fixes two claims in the revised articles. In
translate-conditional-jsx, gt-next'sLinkdoes not prefix the default locale, so the example now reads/es/termsfor a Spanish visitor. Inmultilingual-nextjs-seo, the unsourced claim that Profound's main product is built with the Next.js App Router is replaced by the figure /enterprise publishes (47+ locales across platform and docs).