Locale Tag Builder

This page explains what the Locale Tag Builder does, how to select the right ISO codes for your locale, the step-by-step process for building locale-specific hreflang tags, the technical details behind locale construction, common ISO code mistakes, and how this tool compares to a general hreflang tag generator.

What is a locale tag builder?

A locale tag builder is a hreflang tool focused on the precise construction of locale identifiers — the language-REGION codes that sit inside every hreflang attribute. While most hreflang tools treat locale selection as a secondary input field, this builder puts it front and center. It guides you through the ISO 639-1 language code catalog and the ISO 3166-1 alpha-2 region code catalog, helps you pick the correct combination for your target audience, and then generates the full hreflang annotation set.

The term "locale" in hreflang context means a specific combination of language and optional region: en is a language, en-US is a locale, and en-GB is a different locale. Getting the locale wrong — using a non-existent code, swapping language and region, or mixing up similar codes — silently breaks your hreflang implementation. Search engines ignore annotations with invalid locale identifiers without reporting any error.

How to use the locale tag builder

Follow this process to construct technically correct locale tags:

1. Start with the language code. Select your language from the ISO 639-1 list. The tool provides an autocomplete dropdown with all 184 two-letter language codes. Each entry shows the English name and native name of the language to prevent confusion between similar codes (e.g., no for Norwegian vs. nb for Norwegian Bokmal).
2. Add a region code if needed. If your site serves multiple regional variants of the same language, select the ISO 3166-1 alpha-2 region code. The dropdown filters to show only regions where your selected language is commonly used, though you can override this filter for edge cases.
3. Enter the URL for each locale. Paste the absolute HTTPS URL that serves content for this locale. The tool validates the URL format and checks for protocol consistency.
4. Repeat for every locale your page supports. Add all language and language-region variants. Include an x-default entry for your fallback page.
5. Review and generate. The validation panel checks every locale identifier against the ISO standards, flags duplicates, verifies reciprocity and self-references, and confirms URL formatting. Once all checks pass, generate your output in HTML, HTTP header, XML sitemap, or JSON-LD format.

Deep dive: understanding locale codes in hreflang

The hreflang specification builds on two ISO standards, and understanding them prevents the majority of implementation errors.

ISO 639-1: language codes. This standard defines two-letter codes for languages: en for English, es for Spanish, de for German, zh for Chinese, ja for Japanese, ar for Arabic, and so on. Hreflang requires ISO 639-1 specifically — not ISO 639-2 (three-letter codes like eng) or ISO 639-3 (which covers thousands of minority languages). If your language does not have a two-letter ISO 639-1 code, hreflang cannot represent it.

ISO 3166-1 alpha-2: region codes. This standard defines two-letter codes for countries and territories: US for the United States, GB for the United Kingdom, DE for Germany, BR for Brazil, CN for China. Hreflang uses these as an optional refinement after the language code. The region is always uppercase in the specification, though search engines normalize case. The tool enforces uppercase to keep your annotations clean.

Combining them correctly. The format is always language-REGION with a hyphen separator — never an underscore, never a space, never a slash. The language part is lowercase, the region part is uppercase: en-US, pt-BR, zh-CN. Common mistakes include en_US (underscore), EN-us (wrong case), and us-en (reversed order). The locale tag builder auto-corrects case but rejects structurally invalid inputs.

Special cases worth knowing. Chinese has two major written forms: zh-CN for Simplified Chinese (mainland China) and zh-TW for Traditional Chinese (Taiwan). Portuguese has notable differences between pt-BR (Brazilian Portuguese) and pt-PT (European Portuguese). Serbian can be written in Latin or Cyrillic script, which ISO 639-1 alone cannot distinguish — hreflang handles this at the region level (sr-RS for Serbia, sr-BA for Bosnia).

For more on locale strategy in international SEO, see the hreflang implementation guide.

Common errors and how to fix them

These locale-related mistakes are the ones this tool is specifically designed to prevent:

1. Using three-letter language codes. Codes like eng, spa, or deu come from ISO 639-2 or 639-3, not ISO 639-1. Hreflang requires the two-letter form. The tool rejects any language code longer than two characters.

2. Confusing language codes with region codes. DE is the region code for Germany. de is the language code for German. Writing hreflang="DE" means nothing valid in the spec. The tool enforces the language or language-REGION structure and does not accept a bare region code.

3. Using en-UK instead of en-GB. This is the single most common region code mistake in English-language SEO. The ISO 3166-1 code for the United Kingdom is GB (from "Great Britain"), not UK. The tool rejects UK and displays the correction.

4. Inventing locale codes. There is no es-LA for "Latin American Spanish" or en-EU for "European English." Hreflang region codes map to specific countries, not geographic regions. To target Latin America, you need individual country codes (es-MX, es-AR, es-CL, etc.) or a generic es fallback.

5. Omitting the language code entirely. A bare region code like hreflang="US" is invalid. The language component is mandatory; the region component is optional. The tool requires a language code for every entry.

How this tool is different

The locale tag builder is uniquely focused on getting the ISO code layer right:

• Guided code selection. Instead of a text input where you type a code from memory, the tool provides searchable dropdowns for both language and region codes, with descriptions and usage notes for each option. This eliminates typos and guesswork.
• Common-pair suggestions. When you select a language, the tool suggests the most common region pairings. Select es and it highlights ES, MX, AR, CO, CL, and PE as frequently used combinations. This speeds up data entry for multi-region setups.
• Validation depth. Beyond checking that a code exists in the ISO standard, the tool warns on unusual combinations — like de-US (German for the United States) — that are technically valid but often indicate a data-entry error.
• Locale coverage matrix. A summary table shows which language-region combinations you have defined, making it easy to spot gaps in your locale coverage before generating output.

For general hreflang generation, start with the hreflang tag generator. For workflows focused on regional variants of the same language, the multi-region tag builder is purpose-built for that scenario.