Language and locale¶

Identify the language of the actual content. A language, writing system, region, and set of formatting preferences are related but distinct.

Choose a precise identifier¶

Use BCP 47 language tags in interchange and web content. Prefer the registered two-letter language subtag when one exists. Add a script, region, or variant only when the distinction matters. For example, Serbian in Latin script needs a different writing-system identifier from Serbian in Cyrillic. A reader’s location does not prove which language or script they use.

The short filenames in this guide are catalog aliases. pt.md contains the Brazilian Portuguese guide, while pt-pt.md contains the European Portuguese guide. A runtime tag pt does not itself mean Brazil. Likewise mn-legacy and es-neutral are catalog edition labels, not tags to copy into HTML. Use mn for the actual Mongolian content and choose a real Spanish tag from the content’s scope.

Do not equate Filipino (fil) with Tagalog (tl) merely to get a two-letter filename. Do not replace Valencian with an unrelated three-letter code; ca-valencia preserves the registered variant.

Mark the content¶

Set the default language on the HTML document. Mark a passage in another language at the element containing it. Language metadata can affect speech pronunciation, spelling, font selection, and text processing; a page title or a country flag does not replace it.

<html lang="en">
  <body>
    <p>The Polish term is <span lang="pl">glif</span>.</p>
  </body>
</html>

Set direction separately. lang="ar" does not replace dir="rtl". For text received through an API, retain language and direction metadata where the format supports them. Do not discard that information when copying a label into another screen.

Review a language handoff¶

Record the target language, relevant region, script, source revision, register, and terminology status. Keep proposed terms separate from approved terms. If a language has no region-specific guidance here, ask a reviewer to resolve the missing convention instead of treating a nearby locale as interchangeable.