The Road to Globalization of HarmonyOS Next Applications: Internationalization and Localization

This article aims to deeply explore the technical details of the Huawei HarmonyOS Next system (up to API 12 as of now) in terms of application internationalization and localization, and is summarized based on actual development practices. It mainly serves as a carrier for technical sharing and communication. Mistakes and omissions are inevitable. Colleagues are welcome to put forward valuable opinions and questions so that we can make progress together. This article is original content, and any form of reprint must indicate the source and the original author.
In today's era of globalization, application internationalization and localization have become key factors in enhancing user experience and expanding market share. The Huawei HarmonyOS Next system provides powerful tools and functions for developers to help create cross-language and cross-cultural applications. This article will introduce in detail the concepts, advantages, processes, and key steps of internationalization and localization of HarmonyOS Next applications, helping developers embark on the road to application globalization.

I. Concepts and Differences between Internationalization and Localization

(I) Internationalization (Internationalization, I18n)

Internationalization refers to the process of designing and developing an application so that it can adapt to different languages, regions, and cultures. It involves not only simple language translation but also the adaptation of various formats such as dates, times, numbers, currencies, weights and measures, as well as the universal design of interface layouts, icons, colors, and other elements. The goal of internationalization is to create an application that can be used globally without extensive code modifications. For example, in an internationalized application, the date format may be displayed in different styles depending on the user's region, such as "YYYY-MM-DD" (China) or "MM/DD/YYYY" (United States).

(II) Localization (Localization, L10n)

Localization is the process of customizing and optimizing an application for a specific target language and region on the basis of internationalization. This includes translating the interface text of the application into the local language, adjusting the interface layout to adapt to different text lengths and reading habits, and using local cultural elements and symbols. Localization ensures that the application can provide a natural, smooth, and user-expected experience in each target market. For example, when localizing an English application to Japan, not only should the text be translated into Japanese, but the interface layout may also need to be adjusted to adapt to the display of Japanese characters, and Japanese cultural elements may be used to enhance user affinity.

(III) Differences between the Two

Internationalization focuses on building the general framework and infrastructure of an application to enable it to support multiple languages and cultures; while localization is the personalized adaptation and optimization of an application for specific languages and regions. Internationalization is a global and forward-looking design concept, while localization is the actual implementation for specific markets on the basis of internationalization.

II. Advantages of Internationalization and Localization of HarmonyOS Next Applications

(I) Expanding the Global Market

Through internationalization and localization, applications can break through language and cultural barriers, attract users from different countries and regions, greatly expand market coverage, and increase the potential user base.

(II) Enhancing User Experience

Providing users with interfaces and functions that conform to their language habits and cultural backgrounds enables them to use the application more naturally and conveniently, thereby increasing user satisfaction and loyalty.

(II) Strengthening Competitiveness

In the global market competition, applications with internationalization and localization capabilities have an advantage, can better meet user needs, compete with local competitors, and enhance brand image and market share.

(IV) Reducing Development Costs

Adopting internationalization and localization design methods and following certain norms and standards during the development process can reduce the costs of separate development and maintenance for different languages and regions in the later stage.

III. Processes of Internationalization and Localization of HarmonyOS Next Applications

(I) Requirement Analysis

1. Target Market Research: Understand the potential markets of the application, including factors such as languages, cultures, user habits, and laws and regulations in different regions. For example, certain regions may have different cultural meanings for specific colors or icons, which need to be considered in the design.
2. Function Requirement Evaluation: Determine the functions that the application needs to support in different language and cultural environments, such as multi-language input, payment methods in different regions, and localized push notifications. ### (II) Design Stage
3. Interface Layout Design: Adopt a flexible layout method and reserve sufficient space to adapt to the length changes of different language texts. At the same time, consider functions such as interface mirroring to support the display requirements of right-to-left (RTL) languages such as Arabic.
4. Resource Separation: Separate interface texts, pictures, audio, and other resources from the code logic to facilitate subsequent translation and replacement. For example, store all string resources in independent files instead of hard-coding them in the code. ### (III) Development Stage
5. Using the Internationalization Framework: Utilize the internationalization and localization development services provided by HarmonyOS Next, such as the Localization Kit, to perform language and region-related settings, resource loading, and format conversions.
6. Function Implementation and Adaptation: According to the requirement analysis, implement functions that support multiple languages, such as displaying the corresponding interface according to the user's language setting and handling date and time formats in different regions. ### (IV) Testing Stage
7. Language Testing: Have local language experts or users test the translation accuracy, language fluency, and interface display of the application to ensure the quality of the application in different language environments.
8. Localization Testing: Include interface layout testing, function compatibility testing, and cultural adaptability testing to check whether the application can operate normally in each target region and meet the expectations of local users.
9. Pseudo-Localization Testing: Before formal localization, simulate the localization process by using pseudo-translated texts and special test regions (such as en-XA) to discover potential localization problems such as interface truncation and incorrect text direction. ### (V) Release and Maintenance Stage
10. Multi-Language Version Release: Release the application in corresponding language versions according to different target markets.
11. Continuous Optimization: Collect user feedback, promptly fix localization-related problems, and continuously update and optimize the internationalization and localization content of the application according to market changes and user needs. ## IV. Key Steps of Internationalization and Localization of HarmonyOS Next Applications ### (I) Setting the System Language and Region
12. Obtaining the System Language and Region: Use the methods i18n.System.getSystemLanguage() and i18n.System.getSystemRegion() to obtain the language and region information of the current system.
13. Setting the Application Preferred Language: The method i18n.System.setAppPreferredLanguage() can be used to set a specific preferred language for the application, so that the application loads the corresponding resources according to the user's setting or the default language when it starts. For example:

import { i18n } from '@kit.LocalizationKit';
import {BusinessError } from '@kit.BasicServicesKit';
try {
    i18n.System.setAppPreferredLanguage("zh-Hans"); // Set the application preferred language to Simplified Chinese
} catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Failed to set the application preferred language, error code: ${err.code}, message: ${err.message}.`);
}

(II) Resource File Configuration and Management

1. Determining the Target Region: Clearly define the languages and regions that the application needs to support, referring to the region identifier (consisting of language, script, country/region, and extension parameters).
2. Creating Resource Directories and Files:     - Resource directories include the default (base) directory and qualifier directories (such as resources/en_GB-vertical-car-mdpi). The default directory stores general resources, and the qualifier directories are customized according to languages, scripts, etc., and are used to store resources for specific regions.     - Create resource files (such as .json files) in the corresponding directories and classify and store resources such as strings, pictures, and audio. For example, store string resources in different languages in the strings.json file in the corresponding language directory.
3. Resource Matching Rules: The application matches the user's language preference list with the resource directories and displays the most matching resources first. If no matching resources are found, the content in the default directory is used. ### (III) Interface Text Processing
4. Avoiding Hard Coding: Extract all the text displayed on the interface to resource files and load them using relevant interfaces, avoiding directly hard-coding strings in the code. For example, define in the strings.json file:

{
    "name": "welcome_message",
    "value": "欢迎使用应用"
}

Then obtain and display this string in the code through the resource loading mechanism.

1. Supporting Singular and Plural Forms: According to the singular and plural rules of different languages, use methods such as getPluralStringValueSync to correctly handle the singular and plural forms of nouns or unit expressions. For example, in English, for the word "apple", display "apple" (singular) or "apples" (plural) depending on the quantity. ### (IV) Internationalization of Dates, Times, Numbers, and Weights and Measures
2. Date and Time Formatting:     - Use the format interface of the DateTimeFormat class to format date and time objects into appropriate strings according to the language and cultural habits of the user's region. For example:

import { intl } from '@kit.LocalizationKit';
let date = new Date(2021, 8, 17, 13, 4, 0);
let dateFormat1 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'full', timeStyle: 'full'});
let formattedDate1 = dateFormat1.format(date); // 2021年9月17日星期五 中国标准时间 13:04:00

    - At the same time, pay attention to handling daylight saving time transitions to ensure that the application displays the correct time during daylight saving time. The Calendar class can be used to obtain and set time zones, calculate time offsets related to daylight saving time, etc.

1. Number and Weights and Measures Formatting:     - Through the format interface of the NumberFormat class, format numbers according to the user's region settings, including decimal separators, grouped displays, and currency symbols. For example:

import { intl } from '@kit.LocalizationKit';
let numberFormat1 = new intl.NumberFormat('zh-CN', {notation:'scientific', maximumSignificantDigits: 3});
let formattedNumber1 = numberFormat1.format(123400); // 1.23E5

    - For weights and measures conversion, use the unitConvert interface of the I18NUtil class to perform unit conversion and formatting according to different weights and measures systems.

(V) Localization Testing and Optimization

1. Comprehensive Testing: Conduct language testing, localization testing, and pseudo-localization testing to cover all functions and interface elements of the application. During the testing process, check issues such as translation accuracy, interface layout rationality, and cultural adaptability.
2. Problem Fixing and Optimization: According to the testing results, promptly fix the discovered problems and optimize the application. This may include adjusting the interface layout, modifying the translation text, optimizing resource loading, etc. At the same time, continuously monitor user feedback and continuously improve the internationalization and localization quality of the application. ### (VI) Continuous Update and Maintenance
3. Language and Resource Updates: With the changes in the market and the evolution of user needs, promptly update the language resources of the application, including the update of translation texts and the support of new languages.
4. Function Adaptation and Optimization: According to the user feedback and market needs in different regions, adapt and optimize the functions of the application to ensure that the application always maintains a good user experience globally. Through the above steps, we can gradually realize the internationalization and localization of HarmonyOS Next applications and create high-quality applications that adapt to the global market. In the actual development process, various language and cultural differences need to be fully considered, attention should be paid to details, and continuous optimization should be carried out to meet the diverse needs of users in different regions.