Skip to content

docs(kb): revise the five original articles for answer engines - #650

Merged
Kevin-Liu-01 merged 25 commits into
mainfrom
k/kb-article-edits
Oct 22, 2026
Merged

Kevin-Liu-01 merged 25 commits into
mainfrom
k/kb-article-edits

Conversation

@Kevin-Liu-01

@Kevin-Liu-01 Kevin-Liu-01 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

#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.

Article Judges cite the revision Passage score, revision vs main (1 to 5) Passages that name General Translation, revision vs main
how-to-handle-plurals-in-react 40 of 40 4.58 vs 2.29 15 vs 10
multilingual-nextjs-seo 40 of 40 4.59 vs 2.88 33 vs 15
i18n-without-translation-files 39 of 40 4.95 vs 3.90 40 vs 32
best-localization-software 40 of 40 4.14 vs 2.94 40 vs 28
translate-conditional-jsx 34 of 40 4.60 vs 2.35 36 vs 16

The 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-seo and i18n-without-translation-files were rewritten so each section answers one real question on its own and names General Translation in the sentence that makes the claim.
  • best-localization-software gets back the original's arithmetic on what hand-maintained JSON files cost, and its long sections are split into single-question passages.
  • translate-conditional-jsx adds a variable and a link inside one translated sentence, and how nested elements work with react-i18next's Trans compared with <T>.

Every fact was checked against docs/en-US.

After review, best-localization-software gained 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 LocaleSelector import and the Dark Mode snippet), so the rebase keeps the tested text. The Next.js example imports LocaleSelector from gt-next, as the Next.js quickstart does.

Checks

All content validators pass on this branch (npm test, the six validate:* 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's Link does not prefix the default locale, so the example now reads /es/terms for a Spanish visitor. In multilingual-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).

Kevin-Liu-01 and others added 8 commits October 16, 2026 18:11
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>

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@pie575

pie575 commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Kevin, a few changes we'd like before publishing, primarily in kb/best-localization-software.mdx:

  1. Restore a dedicated pricing section. Your rewrite removes “Pricing that scales with usage, not headcount” and distributes those details elsewhere. I think retain a self-contained answer explaining current usage-based pricing, unlimited seats, and how costs scale is an important part of this article.

  2. Be more specific about when and why readers should choose an alternative to GT. The article recommends a TMS when a separate localization team owns translations or content lives outside the codebase. Those circumstances also fit GT, so they are too broad to justify recommending another product. Please identify the particular workflow or capability a reader needs and explain why an alternative is a better fit for that requirement. This is about making the reasons for the recommendation more specific, not replacing named-product comparisons with a generic “traditional TMS” category. Apply that specificity to the repeated recommendations and takeaway too.

  3. Lead with Locadex's customization. The automation section currently emphasizes PR generation and auto-merge being off by default. We should explain that users can customize when workflows trigger, which files/content/code they change, and how changes are delivered in GitHub. Illustrate the currently supported options rather than presenting the default workflows as the full capability. Default settings can remain in the linked setup documentation.

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.

Kevin-Liu-01 and others added 4 commits October 21, 2026 16:14
- 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>
@Kevin-Liu-01

Kevin-Liu-01 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor Author

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:

  • Phrase TMS, for agencies that work in XLIFF or Office files
  • Lokalise's OTA SDK, for native apps that update text without an app store release
  • Weblate and Tolgee, for a self-hosted platform
  • Transifex Live, for translating a website with a snippet
  • Crowdin, for its free open-source license

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:

  • When it runs: Run when, Target branch, the /locadex comment, Active
  • What it changes: the three templates, Target directory, Changed files only, Preserve local edits, and pre-process and post-process commands
  • How changes reach GitHub: Created branch prefix, the pull request against the target branch, the link comment on a triggering pull request, reuse of the open pull request, custom title, description and commit message, and Auto-merge

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 updated to 2026-10-21.

Update: the remaining conflict with main is resolved in 1ca4283; see the comment below.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

Kevin-Liu-01 and others added 3 commits October 21, 2026 16:26
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>
Kevin-Liu-01 and others added 2 commits October 21, 2026 16:31
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>
@Kevin-Liu-01

Copy link
Copy Markdown
Contributor Author

Synced with main through #649's branch in 1ca4283, which clears the conflict. Following #671, the five revised articles are now in kb/en-US/. Each keeps this PR's summary and has a description from #662, rewritten to match the revised summary. The four articles that still said updated: 2026-10-16 now say 2026-10-21 (b10e1a9). All content checks and the content app build pass.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

Kevin-Liu-01 and others added 3 commits October 21, 2026 21:15
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>

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

Base automatically changed from k/kb-new-articles to main October 22, 2026 19:10
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: medium. Left a non-blocking comment; this PR is not approved. Rewriting five published knowledge-base articles is more than low-scope, so human review is needed and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@Kevin-Liu-01
Kevin-Liu-01 enabled stacked auto-merge (squash) October 22, 2026 19:35

@pie575 pie575 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Image

@Kevin-Liu-01
Kevin-Liu-01 merged commit f2c56c3 into main Oct 22, 2026
8 checks passed
@Kevin-Liu-01
Kevin-Liu-01 deleted the k/kb-article-edits branch October 22, 2026 20:03
kevinwu98 added a commit that referenced this pull request Oct 23, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants