How UEFI Handles Localized String Tables

UEFI systems manage multi-language setup utilities through the Human Interface Infrastructure (HII) database using dedicated, tokenized string packages. Instead of hardcoding text into firmware drivers, the UEFI framework abstracts user-facing text into language-specific catalogs identified by standard language codes. When a user selects a language in the BIOS/UEFI setup utility, the firmware dynamically queries the HII database using abstract string identifiers, allowing the interface to render the appropriate translation seamlessly without modifying the underlying form logic.

The Role of the HII Database

The core of UEFI localization is the Human Interface Infrastructure (HII). Firmware drivers that expose user interfaces submit their configuration forms, fonts, and strings to the centralized HII database as an EFI_HII_PACKAGE_LIST.

A package list contains distinct package types:

  • Form Packages: Define the layout, menus, and controls using Visual Forms Representation (VFR).
  • String Packages: Contain the actual localized text arrays.
  • Font Packages: Provide glyphs necessary to render specific scripts, such as Cyrillic or East Asian ideographs.

By separating the visual layout from the textual presentation, the setup utility can alter the display language on the fly without reloading or rebuilding the menu hierarchy.

Structure of UEFI String Packages

A string package is defined by the EFI_HII_STRING_PACKAGE_HDR structure. Each package is explicitly associated with a single language using an RFC 4646 language tag (such as en-US, fr-FR, or zh-Hans), which completely replaced the older ISO 639-2 three-letter codes used in legacy EFI specifications.

Inside the package, strings are stored sequentially and assigned a numerical EFI_STRING_ID (often referred to in code as a STRING_TOKEN). These tokens are uniform across all localized packages for a given driver. For instance, STRING_TOKEN(STR_BOOT_ORDER) will map to integer 0x0004 regardless of whether the system is querying the English, French, or Japanese string package. The text itself is typically encoded in UCS-2 or UTF-8, ensuring compatibility across different character sets.

String Resolution and the HII String Protocol

When the UEFI Setup Browser renders a menu, it relies on the EFI_HII_STRING_PROTOCOL to resolve tokens into human-readable text. The process works as follows:

  1. Language Determination: The platform reads the global NVRAM variable PlatformLang to identify the current user-selected language. The related variable PlatformLangCodes lists all languages officially supported by the firmware.
  2. String Lookup: The browser calls the GetString() function exposed by EFI_HII_STRING_PROTOCOL, passing the target HiiHandle, the EFI_STRING_ID, and the active language tag.
  3. Extraction: The protocol locates the registered string package matching the requested language and extracts the string corresponding to the ID.
  4. Fallback Handling: If a string is missing in the primary requested language, the HII engine implements a fallback mechanism, typically defaulting to the base language dialect (e.g., falling back to en if en-GB is not present) or returning the system default language (usually en-US).

Build-Time Compilation

During the platform build process, localized strings are managed using Uni (Unicode) source files. Developers define entries pairing tokens with their translated values:

#string STR_BOOT_ORDER   #language en-US  "Boot Order"
                         #language fr-FR  "Ordre de démarrage"
                         #language de-DE  "Boot-Reihenfolge"

The build tools parse these .uni files and automatically generate both the binary HII string packages embedded within the driver executable and the C header files containing the string token definitions. This ensures complete synchronization between the forms defined in the driver and the available translations at runtime.