Skip to content

docs(kb): add 18 informational Knowledge Base articles - #663

Merged
pie575 merged 34 commits into
mainfrom
kb/informational-articles
Oct 23, 2026
Merged

pie575 merged 34 commits into
mainfrom
kb/informational-articles

Conversation

@kevinwu98

@kevinwu98 kevinwu98 commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds 18 informational Knowledge Base articles and updates 3 live ones. Each article opens with a direct, quotable answer, cites primary sources, and keeps General Translation to one section after the neutral answer.

New articles

  • Internationalization: detect-user-language, find-hardcoded-strings, i18n-key-naming, internationalization-vs-localization, language-switcher, localize-ios-app, make-website-multilingual, pseudo-localization
  • Locale formatting: icu-message-format, right-to-left-css
  • Multilingual SEO: locale-routing-seo, multilingual-url-structure, what-is-hreflang
  • Translation: is-ai-translation-accurate, translate-json-files, translate-markdown-files, translate-srt-subtitles
  • Workflow tools: what-is-a-translation-management-system

Updated live articles

  • multilingual-nextjs-seo: uses prefixDefaultLocale: true throughout and builds the canonical, hreflang, noindex, and sitemap from one record of each page's published locales. It shows the <head> and sitemap output of a real build, including a page with a missing translation.
  • multilingual-app-launch-checklist: retitled to "Localization testing checklist for multilingual apps". General Translation notes are consolidated into one section, FAQs that duplicated other articles are removed, and a sample release record is added.
  • general-translation-vs-tms: retitled, with a neutral summary and Crowdin's hourly GitHub sync default (cited). Customer name-drops and Enterprise plugs are removed.
  • Link text on the Crowdin, Lokalise, Phrase, Smartling, Symfony Translation, and Transifex comparisons now matches the new general-translation-vs-tms title.

Search and answer-engine work

  • Titles use searched wording, and descriptions state the answer within about 155 characters.
  • Summaries answer the title first and keep their key qualifications.
  • 19 answer sections use question headings, such as "Should you redirect visitors by browser language?"
  • Each shared topic has one owning article; other articles keep a short line and link to it. For example, the order of language signals lives in locale-routing-seo, hreflang rules in what-is-hreflang, and plurals in icu-message-format.
  • Neutral tables and sections contain no product rows.
  • Planned locale-codes and translate-android-strings articles were dropped because they competed with /docs/platform/core/guides/locale-codes and /docs/cli/reference/formats/android-strings-files. Links point to those docs pages instead.

Validation

  • validate-kb (52 articles), validate-links, validate-reference-links, and validate-unsafe-html pass.
  • Quotes and claims attributed to Google, MDN, W3C, WCAG, RFCs, Apple, Android, Tailwind, Crowdin, React Native, and WMT25 were checked against the live sources. The SOC 2 Type 2 and ISO 27001 claim matches the trust portal.
  • Executed examples, with output shown in the articles:
    • Next.js 16.4.2 with gt-next 11.4.14: the routing redirects, <head> tags, noindex, and sitemap.
    • i18next 26.5.3: namespace lookups, and Polish plural selection with and without the few and many keys.
    • The SRT checker on the Spanish and German inputs now shown in the article.
    • Chrome 155: physical vs. logical margins in right-to-left text.
    • The TypeScript-aware ESLint config in find-hardcoded-strings.
  • getTextInfo() browser support was checked against @mdn/browser-compat-data.

Limits

  • Local checks used Node.js 24; CI runs Node.js 22.
  • The Polish example strings were written for the article and haven't been reviewed by a native speaker.
  • No live translation API call, full Android build, or Xcode run was made for this revision.
  • Tests don't establish translation quality, search rankings, or AI-answer citations; measure those after publication.
  • docs/en-US/cli/quickstart.mdx still says the CLI needs Node.js 20, but the published gt package declares no engines field. That docs page is outside this PR.

🤖 Generated with Claude Code

@kevinwu98
kevinwu98 requested review from a team as code owners October 20, 2026 18:39

@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. I left a non-blocking comment and did not approve this PR because 21 new public Knowledge Base articles are above the low-risk, small-blast-radius bar. Human review is needed, and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@kevinwu98
kevinwu98 force-pushed the kb/informational-articles branch from 663da2c to d04ed35 Compare October 20, 2026 19:07
@kevinwu98
kevinwu98 changed the base branch from main to kb/seo-titles-descriptions October 20, 2026 19:07

@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. I left a non-blocking comment and did not approve this PR because 21 new public Knowledge Base articles are above the low-risk, small-blast-radius bar. 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. I left a non-blocking comment and did not approve this PR because 21 new public Knowledge Base articles are above the low-risk, small-blast-radius bar. Human review is needed, and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@kevinwu98
kevinwu98 removed this pull request from stack #664 October 20, 2026 19:25
Base automatically changed from kb/seo-titles-descriptions to main October 20, 2026 21:19
kevinwu98 and others added 2 commits October 20, 2026 14:44
Concept, how-to, best-practice, and troubleshooting answers for common
localization questions that the Knowledge Base didn't cover yet:

- Internationalization: i18n vs. l10n, making a website multilingual,
  detecting the user's language, language switchers, iOS String Catalogs,
  Android strings.xml, finding hardcoded strings, i18n key naming, and
  pseudo-localization
- Locale formatting: locale codes, ICU message format, and right-to-left CSS
- Translation: AI translation accuracy, JSON locale files, SRT subtitles,
  and Markdown/MDX files
- Multilingual SEO: hreflang, URL structure, and choosing the language
  from the URL, a cookie, or Accept-Language
- Workflow tools: translation management systems and Docusaurus sites

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each summary runs past the 200-character meta description limit that
#662 adds to validate-kb, so each article gets a description of 200
characters or fewer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kevinwu98
kevinwu98 force-pushed the kb/informational-articles branch from b888199 to 4c91e3b Compare October 20, 2026 21:45
@kevinwu98
kevinwu98 marked this pull request as draft October 20, 2026 21:45

@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. I left a non-blocking comment and did not approve this PR because 21 new public Knowledge Base articles are above the low-risk, small-blast-radius bar. Human review is needed, and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

kevinwu98 and others added 5 commits October 20, 2026 17:37
The output string contained a bare {name}, which MDX evaluates as a
JavaScript expression, so prerendering /kb/icu-message-format failed
with "name is not defined" in the content app build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Add authors: [kevin-wu, jackie] to all 21 articles, matching the
  existing Knowledge Base convention.
- Turn generic headings into the questions readers ask, and give the
  General Translation sections specific names.
- Drop marketing lines and stamped customer quotes in favor of plain
  statements, and vary the closing takeaway bullets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kevinwu98 kevinwu98 changed the title docs(kb): add 21 informational Knowledge Base articles docs(kb): add 20 informational articles and validated examples Oct 21, 2026
@kevinwu98 kevinwu98 changed the title docs(kb): add 20 informational articles and validated examples docs(kb): add 20 informational Knowledge Base articles Oct 21, 2026
kevinwu98 and others added 2 commits October 21, 2026 16:36
Accuracy and code:
- language-switcher: quote the W3C globe-icon guidance accurately, add
  WCAG's pronunciation caveat for link lists, link the W3C cookie source,
  and keep a saved cookie from overriding a localized URL.
- multilingual-url-structure: cite Google's localized-versions page for
  the subdomain statement and mark the folder point as an inference.
- multilingual-nextjs-seo: drop the canonical example that pointed the
  default locale at a redirecting /en/ URL, explain the locale-adaptive
  unprefixed URL, and match the URL examples to gt-next defaults.
- make-website-multilingual, locale-routing-seo: disclose that gt-next
  redirects unprefixed URLs by cookie or header and recommend
  prefixDefaultLocale: true for indexed sites.
- find-hardcoded-strings: lint TS and TSX in the combined config.
- i18n-key-naming: warn that extract deletes dynamically built keys and
  point to preservePatterns.
- Android pseudolocales: ar-XB reverses characters; reboot after enabling
  Developer options. Drop unverified Tailwind start/end and Subtitle Edit
  claims, and cite Crowdin's parser configuration.

Search metadata:
- Retitle nine articles toward searched wording and rewrite descriptions
  to lead with the answer within about 155 characters.
- Remove General Translation rows from neutral comparison tables, and
  update link text that quoted old titles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Remove the locale-codes and translate-android-strings articles, which
  competed with the Core locale codes guide and the CLI Android strings
  reference; repoint their links and related entries to those docs pages.
- Rewrite every summary to answer the title first with a concrete,
  quotable detail.
- Give each shared topic one owner: language-signal order and redirects
  (locale-routing-seo), detection and gt-next resolution
  (detect-user-language), hreflang rules (what-is-hreflang), plurals
  (icu-message-format), and pseudo-localization (pseudo-localization).
  Other articles keep a short, context-specific line and link the owner.
  Use one four-step signal order everywhere.
- Fold scattered General Translation notes into one section per article,
  cut customer name-drops and Enterprise plugs, keep one code block at
  most, and keep neutral sections, tables, and takeaways product-free.
- Move testing ahead of the product section in localize-ios-app, drop the
  launch checklist FAQs that duplicated dedicated articles, add the
  Intl.Locale getTextInfo() direction API to right-to-left-css, and cite
  Crowdin's hourly GitHub sync default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kevinwu98 kevinwu98 changed the title docs(kb): add 20 informational Knowledge Base articles docs(kb): add 18 informational Knowledge Base articles Oct 22, 2026
@kevinwu98
kevinwu98 marked this pull request as ready for review October 22, 2026 00:54

@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. I left a non-blocking comment and did not approve this PR because 18 new and 3 updated public Knowledge Base articles are above the low-risk, small-blast-radius bar. Human review is needed, and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

pie575 added 15 commits October 22, 2026 10:40
Restore the four reviewed benefits and current customer proof. Explain catalog retention, generation versus rendering, and independent local delivery while preserving scoped competitor evidence.
Replace the generic closing comparison with concrete generation, context and review mechanisms. Keep vendor selection detail in the comparison hub.
Explain generation and review alongside developer-owned routing, and distinguish inline source authoring from generated translation files.
Include GT where readers compare approaches, attribute extraction and generation correctly, and keep WMT evidence separate from GT quality claims.
Use a supported English-to-German message family, retain Polish validation guidance, and place existing-catalog import before generation. Add concrete context and review guidance.
Include syntax-aware GT generation and reuse in the decision table, and connect shared terminology to built-in review while preserving parser examples.
Reject malformed ranges and nonpositive durations, state checker limits, and explain GT for recurring subtitle updates with video review.
Preserve Xcode agent capabilities and native rendering while explaining import-first generation, target plural handling, shared terminology and current Ramp evidence.
Place context, review, variable handling and configured update tests beside their pass conditions. Keep the release record and remove repeated closing material.
Clear inherited alternate metadata and choose a published x-default destination. Connect reviewed translation generation to publication state and scope the routing recommendation.
Use a resolved preference so the routing example does not duplicate an incomplete language parser. Explain stable localized content URLs with the supported GT configuration.
Add the actual globe and Escape focus behavior, and demonstrate crawlable GT locale links with the active language identified.
Explain complementary pseudo and real-language testing without implying German always expands or that development previews substitute for reviewed release translations.
Distinguish the T component id prop from the translation-function $id option while preserving the naming and maintenance guidance.
Remove an obsolete Locadex plan gate and document the configured compiler and supported Next.js build path required for automatic JSX injection.
Restore the linked Starter price and portable-file takeaway. Use current Ramp, Cursor, and Profound deployments as broader adoption evidence.
Answer the title with the original scoped WMT finding. Keep the GT workflow explanation in the body.
@kevinwu98
kevinwu98 added this pull request to stack #684 October 22, 2026 21:15
kevinwu98 and others added 2 commits October 22, 2026 18:39
docs(kb): strengthen GT guidance and validate examples in #663
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>

@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. I left a non-blocking comment and did not approve this PR because 18 new and 3 updated public Knowledge Base articles are above the low-risk, small-blast-radius bar. Human review is needed, and no reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router

@pie575
pie575 merged commit 1f4606a into main Oct 23, 2026
8 checks passed
@pie575
pie575 deleted the kb/informational-articles branch October 23, 2026 02:40
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