Internationalization, also called “i18n,” is the process of ensuring that your software or application can be easily used and understood by users around the world. Frequently, internationalization is implemented via JavaScript libraries such as i18next and Polygot. However, it is also important to consider internationalization when writing CSS and HTML. This can be achieved by using logical properties, CSS Writing Mode, the dir attribute, and the lang attribute. While you may still need to use JS libraries depending on the complexity of your application, accounting for internationalization in your HTML and CSS can save you time, money, and help ensure your product is inclusive of an international audience.
CSS Logical Properties
English is written in Latin Script which is read from left to right (LTR). Since CSS was originally written for English, many CSS properties rely on physical mapping, such as left, right, top, or bottom. However, languages such as Hebrew, Arabic, Urdu, or Persian use scripts that are read from right to left (RTL). If you are relying on physical properties and change the text direction to RTL, this can cause issues with layout and design. Using CSS logical properties instead of physical properties ensures that styling is maintained when a page is displayed in LTR or RTL. Before the introduction and full support of logical properties, developers would need to have separate CSS files for RTL languages or include inline styling as needed. Both of these lead to an increase in the amount of code and its complexity.
Physical properties use “left,” “right,” “top,” and “bottom” to determine which side of an element is affected. For example, margin-left: 1rem places 1 rem of margin of the left side of an element, regardless of the element’s text direction. Logical properties use “inline” and “block,” with inline representing left and right and block representing top and bottom. When used in combination with inline and block, start and end can offer additional specificity to target the left, right, top, or bottom on element.
For example:
margin-top ➡ margin-block-start ➡
margin-rightmargin-inline-end and
margin-leftmargin-right ➡ margin-inline
See the Pen CSS: physical and logical properties by Sparkbox (@sparkbox) on CodePen.
This CodePen shows two examples of search text with a search icon. The example using physical properties loses the spacing between the icon and the text when the direction toggles from right to left, while the one using logical properties does not.
Some CSS properties do not currently work with logical properties. One example is the transform CSS property which is used to manipulate an element using skew, rotate, and translate. Currently, transform works on an x and y axis and ignores block and inline.
Check out the W3C CSS Working group open issues for more about this and to see other issues related to CSS logical properties.
HTML dir Attribute
In the case mentioned above where Logical properties are not compatible, the HTML dir attribute is useful. This global attribute is used to set an element’s text direction. It accepts LTR, RTL, and auto. You can then use CSS or Javascript to select this attribute and apply styling and behaviors as needed.
See the Pen HTML: dir attribute by Sparkbox (@sparkbox) on CodePen.
In the CodePen above, the .search-icon class is applying margin-right: 10px to the search icon. Then it is also using the CSS attribute selector for dir to change the margin to margin-left when dir=“rtl”. This maintains the layout in both LTR and RTL directions while using physical properties.
HTML lang Attribute and the CSS :lang() Pseudo-class
The lang attribute indicates the language of HTML content. This can be set on the <html> element and on any element where the language changes. So for example, if a French phrase is included on a page that is predominantly English content, the HTML element displaying the translation should have lang=“fr”.
Then, within your CSS, you can target specific languages with the :lang() pseudo-class and address concerns related to text differences in other languages, such as line height and font family.
See the Pen HTML: lang attribute by Sparkbox (@sparkbox) on CodePen.
In the CodePen above, we have two sentences that both appear the same. However, the second sentence includes a <span> which uses the lang attribute to change the language of the portion in French to fr.
Further, the lang attribute can be used to address design differences for specific languages. For example, languages with diacritics, marks above or below the text that indicate pronunciation, may need more space within your layout. The CSS attribute selector for the lang attribute, similar to the dir example, can adjust your layout to account for diacritics when the page is displayed in specific languages.
Using the lang attribute correctly also meets WCAG 2.1 3.1.1 and 3.1.2, and is helpful for users who use screen readers or who use grammar and spelling checkers. An example of a screen reader reading text in an incorrect language is included in Understanding Accessibility: WCAG’s 13 Guidelines with Kasey Bonifacio.
CSS Writing Mode
So far, we have been discussing a horizontal reading direction. However Chinese, Japanese, Korean, and Mongolian all use scripts which can also be read vertically. While most web content in these scripts are read LRT, there are use cases for them to be read vertically and sometimes vertically and horizontally on the same page. This is where CSS writing-mode can be helpful.
The CSS writing-mode property sets the direction in which text flows. It accepts horizontal-tb, vertical-rl, vertical-lr, sideways-rl, and sideways-lr where tb is top to bottom, rl is right to left, and lr is left to right, and horizontal-tb is the browser default.
As explained above logical properties adjust based on the horizontal text direction, this is also true for vertical text-direction, meaning that when the writing mode is switched to a vertical direction, logical properties maintain their design.
See the Pen CSS: Writing Mode by Sparkbox (@sparkbox) on CodePen.
In the CodePen above, if you toggle the writing mode, the example with logical properties maintains its margin as the direction changes, while the example with physical properties does not.
Culturalization
While not specific to HTML or CSS, it’s important to also consider culturalization when discussing internationalization. Culturalization goes beyond internationalization and ensures your product resonates well with users of different cultures. Working with designers and culturalization experts is important to avoid potentially harming your company’s reputation and creating a product that is not inclusive to all users.
For example, in 2015 Yellow Pages released an ad campaign with a depiction of what they called “bibimbap”, a Korean rice dish eaten with a spoon. However, the depiction was of a noodle dish being eaten with chopsticks. More recently in 2023, FEMA distributed paperwork to communities in Alaska with information on how to request assistance after the community was affected by tidal surges and high winds from a nearby typhoon. The paperwork included translations into various Native Languages. However, the translations were inaccurate, confusing, or inappropriate. In both cases, public opinion of the organizations were harmed.
Summary
By accounting for internationalization, you can ensure your product is inclusive to users around the world. Early in the development process of a new product, this may not seem necessary, particularly if your target market is not international. However, by keeping it in mind early and baking it into your CSS, you can avoid needing to refactor a large portion of your code base.
