Implementing UI Internationalization

This topic explains how to implement UI internationalization in an application, including resource configuration and layout adaptation. For details about internationalization guidance, see Localization Kit.

Configuring Internationalization Resources with Resource Qualifiers

To support multiple languages and regions, you can configure localized resources using resource qualifiers in DevEco Studio. For details, see Resource Categories and Access.

Using the Mirroring Capability

Different text alignment modes and reading sequences may be used for different languages. For example, English is read from left-to-right (LTR), and Arabic and Greek are read from right-to-left (RTL). To accommodate diverse user reading habits, ArkUI provides a mirroring capability that can reverse the display content along the x-axis, switching the layout from left-to-right to right-to-left.

Before Mirroring	After Mirroring

The mirroring capability is activated on a component under either of these conditions:

1. The component's direction attribute is set to Direction.Rtl.

2. The component's direction attribute is set to Direction.Auto, and the system language in use (such as Uyghur) is read from right to left.

Basic Concepts

• LTR: left-to-right reading direction
• RTL: right-to-left reading direction

Constraints

ArkUI provides built-in mirroring support for the following capabilities.

However, adaptation is still required in the following three scenarios:

1. For layout and border settings, use the generalized direction terms start and end as parameter types instead of absolute terms such as left, right, x, and y, to accommodate mirroring.

2. The Canvas component offers limited support for mirroring in text drawing only.

3. The XComponent component does not support mirroring capabilities.

Layout and Border Settings

To adapt to mirroring capabilities, update the following universal attributes with new parameter types:

Position settings: position, markAnchor, offset, alignRules

Border settings: borderWidth, borderColor, borderRadius

Size settings: padding, margin

For example, with position, change the absolute directional descriptions of x and y to the new parameter types of start and end.

import { LengthMetrics } from '@kit.ArkUI';

@Entry
@Component
struct InterfaceLayoutBorderSettings {
  build() {
    Stack({ alignContent: Alignment.TopStart }) {
      Stack({ alignContent: Alignment.TopStart }) {
        Column()
          .width(100)
          .height(100)
          .backgroundColor(Color.Red)
          .position({
            start: LengthMetrics.px(200),
            top: LengthMetrics.px(200)
          }) // Use the new LocalizedEdges parameter type added since API version 12 for supporting both LTR and RTL.
        // It is equivalent to .position({ x: '200px', y: '200px' }) when only LTR is supported.

      }.backgroundColor(Color.Blue)
    }.width('100%').height('100%').border({ color: '#880606' })
  }
}

Custom Drawing with the Canvas Component

The drawings and coordinates of the Canvas component do not support mirroring. Content drawn on it does not automatically mirror when the system language changes.

CanvasRenderingContext2D supports mirroring for text rendering, which should be used with the Canvas component's direction attribute and the direction attribute of CanvasRenderingContext2D. The following table lists the specifications.

1. Priority: The direction attribute of CanvasRenderingContext2D takes precedence over the Canvas component's direction attribute, which in turn follows the system language's horizontal display direction.
2. The Canvas component does not automatically mirror with system language changes; applications must listen for system language changes and redraw the content on their own.
3. Only symbols follow the direction setting during text drawing with CanvasRenderingContext2D; Latin characters and numbers do not.

import { BusinessError, commonEventManager } from '@kit.BasicServicesKit';

@Entry
@Component
struct CustomizeCanvasComponentDrawing {
  @State message: string = 'Hello world';
  private settings: RenderingContextSettings = new RenderingContextSettings(true)
  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)

  aboutToAppear(): void {
    // Listen for the system language changes.
    let subscriber: commonEventManager.CommonEventSubscriber | null = null;
    let subscribeInfo2: commonEventManager.CommonEventSubscribeInfo = {
      events: ['usual.event.LOCALE_CHANGED'],
    }
    commonEventManager.createSubscriber(subscribeInfo2,
      (err: BusinessError, data: commonEventManager.CommonEventSubscriber) => {
        if (err) {
          console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
          return;
        }

        subscriber = data;
        if (subscriber !== null) {
          commonEventManager.subscribe(subscriber, (err: BusinessError, data: commonEventManager.CommonEventData) => {
            if (err) {
              return;
            }
            // After detecting the language switch, redraw the content on the Canvas component.
            this.drawText();
          })
        } else {
          console.error(`MayTest Need create subscriber`);
        }
      })
  }

  drawText(): void {
    console.error('MayTest drawText')
    this.context.reset()
    this.context.direction = 'inherit'
    this.context.font = '30px sans-serif'
    this.context.fillText('ab%123&*@', 50, 50)
  }

  build() {
    Row() {
      Canvas(this.context)
        .direction(Direction.Auto)
        .width('100%')
        .height('100%')
        .onReady(() =>{
          this.drawText()
        })
        .backgroundColor(Color.Pink)
    }
    .height('100%')
  }

}

Before Mirroring	After Mirroring

Bidirectional Text Layout and Alignment

Text direction (Direction) defines the order of characters when text is presented on the screen. In left-to-right (LTR) scripts, the display order is from left to right; in right-to-left (RTL) scripts, the display order is from right to left.

Text alignment (TextAlign) affects the layout of text as a whole, with specific positioning influenced by Direction. For example, when TextAlign is set to start, the text is left-aligned if Direction is LTR, and is right-aligned if Direction is RTL.

When LTR and RTL scripts are mixed (for example, an English sentence containing Arabic words or phrases), the display order can become complex. The following figure shows the logical order of characters when numbers and Uyghur are mixed.

In this case, the text rendering engine uses a method called the Unicode Bidirectional Algorithm to determine the character display order. The following figure illustrates the character display order for mixed LTR and RTL scripts. The basic principles for determining character direction are as follows:

1. Strong characters: Strong characters have a definite directionality. For example, Chinese characters are LTR, and Arabic characters are RTL. These characters influence the directionality of surrounding neutral characters.

2. Weak characters: Weak characters do not have a definite directionality. These characters do not affect the directionality of surrounding neutral characters.

3. Neutral characters: Neutral characters do not have a fixed directionality. They inherit the directionality of the nearest strong character. If there are no strong characters nearby, they adopt the global direction.