Balance localization, SEO, and loading behavior

An English URL that translates only navigation still contains a Chinese lesson. Hreflang does not translate the body. Localization needs consistent content, routes, formatting, and page declarations. Performance needs separate measurement of actual loading and interaction.

The case is a bilingual static learning site built with Vite. Internationalization alone does not require a framework migration. Define verifiable language relationships and evaluate loading, responsiveness, and layout stability separately.

Separate interface messages from lessons

Store navigation, buttons, and errors under stable dictionary keys. Keep complete lesson bodies by language. Matching keys do not require literal translations, but technical conditions, examples, and certainty must agree. New controls need entries for every supported language.

If a lesson has no translation, explicitly offer the original or explain its absence. A translated menu does not create a translated lesson. Titles, summaries, image explanations, errors, and exercises also belong to the localized experience.

Use a content ID to map language paths independently of title wording. A title change should not break counterpart identity. Validate dictionary coverage and body availability separately, then connect them during page construction.

Give languages independent stable URLs

Use directly accessible language URLs, such as /learn/ and /en/learn/ on the teaching domain. Switching language should reach the current lesson's counterpart when available, with an explicit fallback otherwise. Do not silently present an unrelated page as the same lesson.

Set HTML lang, title, and description to match the content. Each language's canonical normally identifies its own preferred URL. Canonicalizing every English page to Chinese can confuse the intended independent versions. Standardize duplicate paths, trailing slashes, and redirects.

Hreflang declares alternate-language relationships. Google's guidance requires each version to list itself and the others, using complete URLs and reciprocal links. X-default can identify a language selector or suitable default entry. These declarations neither guarantee indexing or ranking nor replace useful content.

Format values rather than replace strings

Dates, numbers, currencies, and plurals depend on language and regional conventions. Intl supplies formatting facilities. Specify the necessary locale, timezone, and currency instead of depending on the machine default. Keep stored values separate from presentation.

Replacing one currency symbol with another does not convert an amount. Currency conversion requires separate business rules and rate information. Dates also need a defined input format rather than rearranged string fragments. Decide regional variants from product requirements.

Translations change length and wrapping. Test longer English terms and Chinese paragraphs in buttons, cards, and narrow navigation. Avoid fixed-height clipping. Enlarged text, empty values, and errors expose layout constraints that dictionary checks cannot detect.

Check counterpart links offline

The example stores the two URLs and links to the other language. It verifies the destination and reciprocal return. The reserved teaching domain is never requested. The model checks only cross-language mapping, without generating HTML declarations.

pages = {
    "zh": {"url": "https://example.test/learn/", "alternates": {"en": "https://example.test/en/learn/"}},
    "en": {"url": "https://example.test/en/learn/", "alternates": {"zh": "https://example.test/learn/"}},
}
for lang, page in pages.items():
    for other, url in page["alternates"].items():
        assert url == pages[other]["url"]
        assert pages[other]["alternates"][lang] == page["url"]
print([p["url"] for p in pages.values()])

The output is ['https://example.test/learn/', 'https://example.test/en/learn/']. An incorrect link in either direction fails an assertion. Actual hreflang sets must also contain self references and, according to the site's policy, x-default. These alternates intentionally contain only the other language and are not a complete tag set.

The assertions do not establish successful HTTP responses, complete translations, or search-engine acceptance. Inspect generated HTML, redirects, sitemap entries, and deployed content. Correct configuration alone does not verify the resulting pages.

Interpret three performance metrics

LCP concerns loading the main content, INP concerns interaction until the next paint, and CLS concerns unexpected layout shifts. Late discovery of an important image, lengthy synchronous work, and missing image space can affect different metrics, but actual diagnosis requires evidence.

Current web.dev good-experience thresholds are LCP at or below 2.5 seconds, INP at or below 200 milliseconds, and CLS at or below 0.1. Evaluate field data at the 75th percentile, separated by device category. These are criteria, not measurements from this example.

Lab tests support repeatable diagnosis but one successful run does not establish field performance. Cache state, networks, devices, and interaction paths matter. Record conditions before changing resource discovery, script work, or layout reservations.

Verify content and resources after publication

Open both language URLs directly. Check body language, lang, title, description, canonical, and complete hreflang. Test switching, refresh, return navigation, and missing translations. Sitemap entries should use canonical content URLs, not obsolete redirect paths.

Inspect asset size, failures, first-screen images, and font loading. Removing a translation does not fix late resource loading. Test articles with different lengths and states after changing a language template.

Keep explicit user language selection. Browser preferences can support a recommendation without making independent article URLs inaccessible through repeated redirects. Test a copied link in a browser with another preference. Search declarations and user choice are separate responsibilities, and neither replaces missing lesson content.

Exercise: accept a bilingual site

Create two synthetic lessons with complete language counterparts and one Chinese-only lesson. Define IDs, dictionaries, and switching rules. Remove a reciprocal link, dictionary key, and translation deliberately and verify specific errors.

Acceptance requires complete bilingual bodies, counterpart-preserving switches, explicit missing-language fallback, accessible canonical URLs with correct declarations, consistent dates in the specified timezone, and no clipped long text. Distinguish field measurements from lab results. Mapping assertions do not establish search rankings or measured performance gains.