Repository navigation
docs(kb): add 18 informational Knowledge Base articles - #663
Merged
Merged
Conversation
kevinwu98
force-pushed
the
kb/informational-articles
branch
from
October 20, 2026 19:07
663da2c to
d04ed35
Compare
kevinwu98
force-pushed
the
kb/informational-articles
branch
from
October 20, 2026 19:14
d04ed35 to
b888199
Compare
This was referenced Oct 20, 2026
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
force-pushed
the
kb/informational-articles
branch
from
October 20, 2026 21:45
b888199 to
4c91e3b
Compare
kevinwu98
marked this pull request as draft
October 20, 2026 21:45
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>
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
marked this pull request as ready for review
October 22, 2026 00:54
Contributor
There was a problem hiding this comment.
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.
Sent by Cursor Approval Agent: Pull Request Router
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.
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>
pie575
approved these changes
Oct 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


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
detect-user-language,find-hardcoded-strings,i18n-key-naming,internationalization-vs-localization,language-switcher,localize-ios-app,make-website-multilingual,pseudo-localizationicu-message-format,right-to-left-csslocale-routing-seo,multilingual-url-structure,what-is-hreflangis-ai-translation-accurate,translate-json-files,translate-markdown-files,translate-srt-subtitleswhat-is-a-translation-management-systemUpdated live articles
multilingual-nextjs-seo: usesprefixDefaultLocale: truethroughout 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.general-translation-vs-tmstitle.Search and answer-engine work
locale-routing-seo, hreflang rules inwhat-is-hreflang, and plurals inicu-message-format.locale-codesandtranslate-android-stringsarticles were dropped because they competed with/docs/platform/core/guides/locale-codesand/docs/cli/reference/formats/android-strings-files. Links point to those docs pages instead.Validation
validate-kb(52 articles),validate-links,validate-reference-links, andvalidate-unsafe-htmlpass.gt-next11.4.14: the routing redirects,<head>tags,noindex, and sitemap.fewandmanykeys.find-hardcoded-strings.getTextInfo()browser support was checked against@mdn/browser-compat-data.Limits
docs/en-US/cli/quickstart.mdxstill says the CLI needs Node.js 20, but the publishedgtpackage declares noenginesfield. That docs page is outside this PR.🤖 Generated with Claude Code