L04 Internationalization Docs

title: "Internationalizing Documentation for Translation" weight: 4 description: "Learn to internationalize documentation: extracting strings, using resource files, handling pluralization, date/number formatting, text direction, and template configuration for multilingual readiness." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, localization] }

Internationalizing documentation involves separating content from code, using resource files for translatable strings, handling pluralization and formatting, and configuring templates for multilingual support.

In this lesson, you will learn how to internationalize documentation for translation readiness, including string extraction, resource files, pluralization, and formatting.

What You'll Learn

You will learn how to extract translatable strings, create resource files, handle pluralization rules, configure locale-aware formatting, and set up templates for translation.

Why It Matters

Proper internationalization reduces translation effort by 50 percent and prevents formatting errors that require re-translation.

def extract_strings_for_translation(content_files):
    """Extract user-facing strings from content files."""
    strings = []
    for file in content_files:
        with open(file) as f:
            text = f.read()
        strings.extend(extract_translatable(text))
    return strings

Teacher Mindset

Think of internationalization as organizing your closet before moving. Label everything. Pack similar items together. The moving process (translation) goes smoothly when you prepare.

Common Mistakes

1. Concatenating Strings

"Hello " + name + "!" breaks in languages with different word order. Use string templates.

2. Not Handling Pluralization

"1 item(s)" looks unprofessional. Use ICU message format for plural rules.

3. Text in Images

Text in screenshots requires separate translated images. Avoid text in images.

Practice Questions

1. How do you handle pluralization in internationalized content? Use ICU message format or gettext plural forms. Different languages have different plural rules.

2. Why should text not be embedded in images? Images require separate translated versions. Use text overlays or CSS instead.

3. Challenge: Internationalize a documentation template by externalizing all user-facing strings.

FAQ

Mini Project

Take a documentation page. Extract all user-facing strings into a resource file. Handle pluralization for any counted items. Configure locale-aware date formatting. Verify the page renders without hardcoded text.

What's Next

Locale Selection in the next lesson.