Lazarus Free Pascal LCL Localization Guide

Lazarus Free Pascal localization lets developers translate LCL forms, menus and application messages for Windows, Linux and macOS without changing stored records or program logic. If you are searching for how to create Lazarus PO files, use resourcestring, enable Project Options i18n, choose DefaultTranslator or call LCLTranslator.SetDefaultLang, this practical guide explains each decision and how to test the packaged result.

The Lazarus Component Library supports a gettext-oriented workflow for extracting form and resource strings. Enabling i18n in project options and using DefaultTranslator can activate translations for a default language; LCLTranslator provides explicit language selection through SetDefaultLang. Neither mechanism means that every runtime-generated text, third-party component or document becomes translated automatically. Files must be generated, completed, shipped and found in the expected location.

We will follow Harbor Archive, a fictional multilingual library catalog application, from its first English form through translation, build, testing and release. The guide covers resource strings, form files, PO/MO delivery, font rendering, operating-system differences, translation updates, accessibility and common failures. Its aim is to help developers and translators ship a dependable localized program rather than merely produce translated screenshots.

Quick answer: the route to a reliable localized application

Identify the actual Lazarus IDE and its Lazarus Component Library (LCL) version and the translation integration that belongs to it.
List translatable interface labels and protect library item records, due-date notices, accession numbers and catalog search from accidental data rewriting.
Set up Project Options > i18n, translatable form properties, Pascal resourcestring declarations, generated PO/POT catalogs, and the DefaultTranslator or LCLTranslator unit according to the linked documentation.
Translate complete user actions, errors, prompts and accessibility text, not just visible headings.
Choose language and region fallback explicitly; preserve names, codes, numbers and variables.
Inspect full screens in target languages at realistic text sizes and with unusual user data.
Package language resources and fonts with the actual release artifact and test offline.
Block launch for missing critical warnings, broken actions, corrupted data or unreadable scripts.

Who should read this guide?

This is for software developers, translators, QA teams and maintainers who have to deliver Lazarus IDE and its Lazarus Component Library (LCL) software to people using different languages. It is not a promise that any machine translation product knows your domain. A working international interface results from choosing text ownership, collecting accurate context, integrating a supported runtime, and testing what users actually experience. A source-language form caption and a saved accession number have different ownership: the former is translated for display, while the latter must remain stable for data integrity. Use the quick answer as a checklist, then follow the implementation chapters and practical failure cases where they match your product.

What localization changes and what it must never change
A complete platform-specific implementation route
A running production scenario with decisions and acceptance tests
Thirty diagnostic situations and how to fix them
A four-week implementation and review plan
Release checklist and frequently asked questions
Documentation and further reading

What localization changes—and what it must never change

Localization connects the user’s language to the software’s meaning. It includes wording, grammar, context, layout, fonts, input, accessibility, dates and regional habits. It does not give a translated label permission to change data or execution. Consider Harbor Archive, a small desktop collection manager for community libraries. Someone may choose Spanish to read a notice, but their records, permissions and previously saved choices should not be edited merely because a translation was selected. Confusing presentation with identity is one of the easiest ways to ship a beautifully translated yet unreliable application.

Three levels are especially useful. First, source accuracy: the message says precisely what the application does. Second, target-language usability: an actual reader can understand it on a real screen. Third, behavioral integrity: the underlying action, selected record and result are identical before and after the language changes. Measure these separately. A linguistically elegant error can still be wrong if it claims an upload succeeded when a network operation has not completed. A technically correct message can still be unusable if it clips the main verb off a button.

Before translation starts, mark each message’s location, source revision, user action, potential consequence, dynamic variables and reviewer. Distinguish grammatical text from machine identifiers. A source-language fallback is often appropriate for ordinary explanatory labels, but a silent omission of a destructive warning is not. Decide what to show, what to block and what to log. These decisions belong in product specifications so that writers, programmers and testers do not have to improvise different answers in every locale.

Platform-specific implementation: eighteen decisions in a sensible order

1. Decide what belongs in the translation catalog

List TForm captions, TLabel text, menu items, toolbar hints, dialogs and user-facing validation messages; keep database column names and accession numbers unchanged. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. The library uses Save, Export CSV and Delete item; a mistranslated deletion warning could change a real decision. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Walk through every screen and tag strings by source, audience and seriousness. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

2. Enable i18n in project options

Use Project > Project Options > i18n to turn on the Lazarus internationalization pipeline and choose a PO output directory tracked with source. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. A developer may assume adding a language folder is enough although no catalog source was generated. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Build once, inspect the generated POT or PO artifacts and confirm expected form text appears. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

3. Use Pascal resourcestring rather than hard-coded literals

Declare reusable interface messages as resourcestring so the extraction and translator workflow can handle source phrases coherently. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. Harbor Archive displays a validation error from an event handler rather than a design-time caption. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Change the source message and check the next catalog update exposes it for translation. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

4. Distinguish DefaultTranslator from LCLTranslator

DefaultTranslator activates the default language at initialization; explicit choices use LCLTranslator and SetDefaultLang with a selected identifier. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. A preference menu says Japanese while the application still started in its operating-system language. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Verify startup locale and explicitly selected locale in separate launches. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

5. Understand SetDefaultLang parameters

The documented routine accepts Lang, Dir, LocaleFileName and ForceUpdate, and returns the language code used or an empty result on failure. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. A custom product name changes the expected base filename and the program silently misses the catalog. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Log the returned language code, test the directory deliberately and do not assume every redraw is automatic. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

6. Keep locale filenames predictable

Organize locale files with a repeatable basename, language identifier and directory convention; write down which package copies them. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. The Polish catalog is present in a developer folder but absent beside the installed executable. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Compare the final installer tree with the tested lookup paths for each OS. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

7. Preserve PO msgid context

Treat msgid as a source lookup identity, not necessarily a permanent business key; annotate identical words used differently. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. The English word Close appears both on a window button and on a financial-period report. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Ask a bilingual reviewer to inspect the screen context instead of approving isolated dictionary matches. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

8. Update rather than overwrite completed translations

Merge a regenerated template into each target catalog carefully, reviewing new, changed and obsolete entries. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. An English warning gains a condition but a stale translated message still omits that condition. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Diff the source against last release and reapprove all touched strings before compiling. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

9. Know when MO conversion matters

Some delivery workflows use PO text, others use compiled MO catalogs; choose based on what the installed runtime actually searches. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. Development runs from PO files but an installer includes only another format or old compiled files. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Inspect runtime search behavior with a clean installation and remove misleading duplicate catalogs. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

10. Localize form properties and runtime values separately

Design-time form captions may be handled by LCL, while strings assembled in code need explicit resource or lookup treatment. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. A status label updates to English each time a background import completes. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Trace the value’s assignment and rerun the operation after locale selection. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

11. Keep language selection and saved user data independent

Persist locale preference as a setting; never translate user-written notes, saved search keys, paths or accession IDs. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. A user changes to German while editing a note, and an overbroad refresh replaces entered text. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Confirm edits survive a language change and reopen with the same record bytes. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

12. Use Unicode-aware fonts and controls

Check actual glyph coverage, shaping, wrapping, combining marks and platform widget behavior rather than assuming one font solves all languages. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. Arabic labels appear as boxes on one desktop while Japanese filenames display correctly on another. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Run script-specific visual tests under each shipping OS and compare full sentences. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

13. Handle right-to-left interfaces deliberately

Translate meaning first, then inspect ordering, alignment, numeric spans, mixed-script identifiers and any control that lacks RTL behavior. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. A mixed Arabic instruction contains a barcode, quantity and folder path whose order must remain intelligible. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Use native readers to check direction and isolate identifiers where needed. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

14. Format dates and numbers at presentation time

Keep internal timestamps and decimals typed; localize display output without altering stored values or calculations. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. The due date 2026-11-04 becomes ambiguous when rendered as a bare numeric date. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Display long-form dates in critical notices and round-trip typed values during tests. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

15. Preserve keyboard behavior and mnemonics

Review menu accelerators, shortcut conflicts, focus order and any character-based mnemonic after translating labels. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. Two translated menu commands acquire the same keyboard mnemonic and become difficult to reach. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Operate the program without a mouse in every target language. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

16. Review translated warning severity

Risk-bearing dialog text must preserve who acts, what changes, whether the action is reversible and what is not known. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. The Delete permanently action must not become Hide temporarily in translation. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Ask reviewers to explain the consequence without seeing the source text. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

17. Package locale resources for every target

Test executable layout, Linux packages, macOS bundles, file permissions, case sensitivity and startup working directories. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. A release succeeds on a developer machine where the project folder happens to contain old PO files. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Install on clean machines and verify file enumeration with no source tree present. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

18. Maintain a release-grade translation evidence log

Record source revision, catalog revision, OS build, language, reviewer, broken screens and sign-off decisions. In Lazarus IDE and its Lazarus Component Library (LCL), this is not a translation-only question; it defines where the message comes from, when it is rendered and how the program should behave when a requested language or resource is missing. Keep the source-language behavior working while you introduce the target-language path. That gives you a reliable baseline rather than a new system whose errors can no longer be separated from existing defects.

Consider Harbor Archive, a small desktop collection manager for community libraries. Harbor Archive supports six languages but only two have been checked after a new import screen shipped. The practical distinction is between the instruction a person reads and the record or action the program owns. Write the exact before-and-after states on a test card, then read the rendered sentence as a user would. If the target translation changes the actor, the timing, the condition or the consequence, fix the message and its context before adjusting typography.

Use a language-by-platform matrix and block publication for missing critical labels. Do the same check at a cold start, after interacting with the screen and, where relevant, after selecting another language. Include an unusually long translation and a sample with numbers, punctuation or mixed scripts. Note the language identifier, build version and observed result. A screenshot can reveal clipping, but it cannot prove that saved data or action routing remained correct; verify both with a state assertion or repeatable manual workflow.

Worked example: taking a real feature from English to several languages

Imagine an international user opening Harbor Archive for the first time. They can see a dashboard, select a record and change their language without restarting the task. The product description is simple—a small desktop collection manager for community libraries—but the implementation spans a catalog, application state, actual user data and a packaged release. A disciplined team follows the feature from source message to final acceptance, instead of announcing completion as soon as the translation file contains the right words.

Phase A — define an observable user journey

Begin with a real task in library item records, due-date notices, accession numbers and catalog search. Write down exactly which screen appears, which user choice starts the task, what information is entered, and what persisted outcome is expected. Use a second language that noticeably changes word lengths and a third that exercises different writing conventions. The purpose is to locate the point where a translated message could cause the user to choose the wrong action. Test with records that have similar names so an incorrect selection is visible.

Phase B — extract and contextualize the source messages

Move interface-owned phrases through Project Options > i18n, translatable form properties, Pascal resourcestring declarations, generated PO/POT catalogs, and the DefaultTranslator or LCLTranslator unit using the version-appropriate workflow. Give translators a screenshot or short description for each message: a label, an action, a completed-state notification, or an error. Mark variable names explicitly and provide one full example sentence. Do not ask for a dictionary translation of Open or Save without explaining what is opened or saved. If the message is irreversible, document the complete consequence and approved wording.

Phase C — introduce catalog coverage and fallback

Start with one fully functioning target language, not six half-configured ones. Confirm that the initial application startup chooses the expected locale and that every key resolves to an intentional message. Add a deliberately missing noncritical key and see what fallback appears; do the same in a controlled test for a critical warning and verify it cannot fail silently. Keep catalog identities stable during source editing and make changes visible in code review. A source revision must trigger re-review of translations that depend on its meaning.

Phase D — exercise a language switch during real work

Enter a note, choose a record, open a dialog, then change the interface language. The input and selection must still be present. Complete the original operation and compare the resulting record with the same task performed in the source language. Switch languages back and verify the program has not duplicated, deleted or silently converted data. Keep user-entered prose untouched. This test is more valuable than a static screenshot because it checks the boundary between translation and the application model.

Phase E — test with imperfect networks and packaged assets

Use the real release build in an environment that does not contain the source tree. Start offline where the app permits it; exercise errors that depend on network state; inspect language files and font resources. Verify the first screen, secondary windows and reports. If a translation is loaded from a relative path, test launch from an unexpected working directory. If the program is rendered across web and native targets, test every supported deployment separately rather than assuming a development machine proves the release.

Phase F — hand the feature to people who read the target language

Reviewers should finish a scenario without seeing the English source first. Ask them what a warning says will happen, how they would cancel, and how they know whether a task finished. Record confusion as a defect, not as a matter of personal taste. Correct the actual text, the source ambiguity or the interface layout according to evidence. Repeat the original workflow after every fix, since longer wording and different direction can expose a different control defect.

Thirty practical troubleshooting situations

Case 1: The menu stays in English

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: An untranslated form property or missing catalog is still supplying the source caption. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Inspect project i18n, generated catalog and installed locale path; verify the exact menu string exists.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 2: A custom error message stays in English

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: A code literal is outside resourcestring or is constructed dynamically. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Move the user-facing sentence to a resource declaration and rebuild the template.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 3: The selected language is ignored on launch

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: The startup language resolution differs from the preference or argument. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Record the requested locale and the value returned by SetDefaultLang.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 4: The installer works only in the project directory

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: Translation files are absent or searched relative to an unintended working directory. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Install in a clean folder and pass an explicit Dir where appropriate.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 5: The translated button does nothing

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: An event-handler mapping was accidentally coupled to displayed caption text. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Route actions through event identities, never the localized Caption property.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 6: The application cannot find a MO file

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: A wrong catalog naming or file-format convention is used. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Compare actual runtime lookup behavior with the package files and convert only when needed.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 7: An old warning appears after a source change

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: The catalog was not merged and reviewed after the new message. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Update the source template and inspect fuzzy and obsolete entries before approval.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 8: Two languages show identical text

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: The second language fell back to source because of missing translations. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Check expected keys in each locale and document intentional fallbacks.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 9: French punctuation looks cramped

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: Typography and spacing need language-specific review. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Review colons, quotation marks and text wrapping in real forms.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 10: Japanese menu captions are clipped

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: Translated text expands or uses a different font metric. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Resize layout and test actual target fonts at increased display scaling.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 11: Chinese characters show squares

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: A shipping font lacks required glyph coverage. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Test on a clean OS image with no developer fonts installed.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 12: Arabic identifiers appear reversed

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: Mixed script direction is not isolated properly. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Check text, numbers and filenames together with a native speaker.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 13: A numeral changes meaning after translation

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: Display formatting was confused with stored numeric precision. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Keep typed values; format only at final presentation.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 14: An import changes decimal values

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: Locale-sensitive parsing was applied to machine-generated exchange data. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Use invariant formats for interchange and locale-aware parsing only for user input.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 15: A user’s notes change when switching language

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: Saved content was wrongly treated as translatable interface text. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Exclude record fields from UI catalog replacement and regression-test preservation.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 16: A dialog reverts to English after refresh

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: A runtime event reconstructs the label from a hard-coded string. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Find the assignment path and apply the selected locale at every update.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 17: The translated notification hides the actor

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: The translation removed who performed an action. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Check source message roles and display concrete agent and object in the target.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 18: The Delete action sounds reversible

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: The translation softened an irreversible warning. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Restore explicit permanence and show reviewers the actual operation.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 19: Shortcut letters collide

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: Localized captions altered mnemonics without rechecking accessibility. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Run keyboard navigation tests after every catalog update.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 20: A file path is accidentally translated

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: Variables and identifiers were not protected in message construction. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Keep paths as interpolated immutable values and display surrounding prose separately.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 21: Catalogs load on Windows but not Linux

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: Case-sensitive filenames or path separators differ. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Compare installation paths and casing; use platform-safe file handling.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 22: The application works on a tester’s laptop only

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: Development resources leak into the runtime search path. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Use a fresh operating-system account and offline packaged build.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 23: The locale preference resets every launch

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: The setting is not persisted or loaded before forms are created. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Save the language independently and apply it before first UI display.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 24: The language switch updates only part of a window

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: Some controls were created after startup or do not refresh automatically. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Enumerate affected controls and retest the same session after switching.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 25: A translator changes a technical label

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: Terminology lacked context about a fixed domain concept. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Give usage screenshots, definitions and glossary decisions for the library workflow.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 26: An empty translation masks a warning

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: A blank target entry was treated as legitimate success. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Treat missing critical target text as a blocking validation failure.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 27: An accessibility label is still English

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: Visible text and accessible naming were not managed together. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Check announced names, form order and descriptions under target locale.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 28: A newly added form has no PO entries

A user reports this after working with Harbor Archive in a non-English locale. Start by reproducing the exact screen and action, not by assuming the translation file is the only problem. Likely cause: Project settings or build extraction did not include the new resource. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Regenerate and inspect the catalog before sending it to translators.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 29: A decimal comma breaks sorting

This is usually discovered during a clean-device test rather than by reading the source. Compare a target-language run with a baseline using the same saved records. Likely cause: Formatted strings were used for comparisons. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Sort typed numeric values and localize only the displayed representation.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Case 30: The rollback package still shows the broken label

Do not repair the visible words before checking the application’s data boundary. A label can look wrong because the underlying state, lookup or bundled resource is wrong. Likely cause: Catalog revision was not tied to the application release. Identify the component, locale, build and reproducible input. Write down both what the person sees and what the application believes has happened; those can be different. This distinction prevents a cosmetic fix from hiding a more serious state or accessibility defect.

Repair: Version and archive installer assets together; validate rollback in a clean environment.. After the change, repeat the original task from a fresh start and again while switching languages mid-task. Check one long translation, an untranslated fallback and a real-world value such as a date or identifier. Record the result in the regression suite. If the case affects permissions, irreversible actions, financial values, user records or serious warnings, block the release until the behavior and the wording both pass review.

Four-week implementation and training plan

Week 1 — inventory and source preparation

Walk through Harbor Archive and identify all messages, user actions, high-consequence warnings and persistent fields. Build a translation spreadsheet with a source key, complete source text, screen context and expected user decision. Configure the source-language catalog, choose target regions carefully, and record the Lazarus IDE and its Lazarus Component Library (LCL) version. Test that the existing app still works with no target catalogs. Assign a developer and language reviewer to the first complete end-to-end screen.

Each week should end with one demonstrable outcome: a usable inventory, a working multilingual feature, reviewed behavior or a clean packaged release. The goal is not to count translated strings. It is to prove that someone using a different language can finish the same real task without extra risk, missing context or changed data. Keep unresolved issues visible rather than disguising them as translation progress.

Week 2 — catalogs, implementation and first language

Integrate Project Options > i18n, translatable form properties, Pascal resourcestring declarations, generated PO/POT catalogs, and the DefaultTranslator or LCLTranslator unit in the application. Translate the selected feature fully, including validation and confirmation states. Add plural and interpolation cases where the workflow needs them. Check an explicit unsupported locale, a missing key and an intentionally long string. Pair every changed message with a screenshot and a corresponding user action. Validate file syntax before the build, and keep record identifiers outside translation files.

Week 3 — usability, scripts and state protection

Test at least three linguistic profiles: one target language with longer phrases, one with a different script and one that exercises punctuation or direction differently. Operate forms while changing language. Verify focus, keyboard and assistive use. Use typed-value comparisons to prove that library item records, due-date notices, accession numbers and catalog search have not changed merely because the UI is localized. Have target-language readers interpret all consequential notices without viewing the source and repair misunderstandings.

Week 4 — production build, rollback and release decision

Install the release package on clean devices or browsers for every advertised target. Verify catalogs, fonts, initial locale, offline behavior and persistence after relaunch. Compare each critical workflow with the source-language baseline. Archive the language review, tested build, outstanding defects and rollback assets together. Publish only when important actions are correct and safe, resource files are present, and the support team knows how to capture a useful locale-specific bug report.

Release checklist

The Lazarus IDE and its Lazarus Component Library (LCL) dependency and localization integration are version-checked.
The first three paragraphs and quick route tell a visitor exactly what this guide solves.
All critical UI strings, prompts, dialogs and error paths have documented owners.
Every translation contains enough context to preserve actor, action, condition and consequence.
Stable identifiers, numeric values, URLs and user content remain unchanged by locale selection.
Plurals, variables, punctuation, dates and text direction were tested in real sentences.
Screen readers, focus order, keyboard and touch operation work in each promised language.
Clean production packages contain catalogs, fonts and the correct resource paths.
Missing-translation and unsupported-locale behavior is documented and tested.
The release has dated sign-off evidence, a rollback plan and a feedback route.

Frequently asked questions

Does Lazarus translate my entire program automatically?

No. i18n support helps with eligible LCL properties and resource strings; runtime content, data and third-party controls still need deliberate work. In practice, start with one complete user task and validate both the words and what the interface does. The right answer depends on the framework and integration version, the supported platform, and the actual languages promised to readers. Avoid changing stored identifiers or user content to solve a display-only problem.

What is DefaultTranslator for?

It activates translation initialization using the default language arrangement defined by the project. In practice, start with one complete user task and validate both the words and what the interface does. The right answer depends on the framework and integration version, the supported platform, and the actual languages promised to readers. Avoid changing stored identifiers or user content to solve a display-only problem.

When do I use LCLTranslator.SetDefaultLang?

Use it when your program explicitly chooses a language or needs to point to a particular catalog directory. In practice, start with one complete user task and validate both the words and what the interface does. The right answer depends on the framework and integration version, the supported platform, and the actual languages promised to readers. Avoid changing stored identifiers or user content to solve a display-only problem.

Can I use PO files?

Yes. Lazarus LCL documentation describes searching PO and/or MO files; confirm the format and naming used by your build. In practice, start with one complete user task and validate both the words and what the interface does. The right answer depends on the framework and integration version, the supported platform, and the actual languages promised to readers. Avoid changing stored identifiers or user content to solve a display-only problem.

Do I need resourcestring?

It is the practical Free Pascal mechanism for user-facing code messages that should be externalized. In practice, start with one complete user task and validate both the words and what the interface does. The right answer depends on the framework and integration version, the supported platform, and the actual languages promised to readers. Avoid changing stored identifiers or user content to solve a display-only problem.

Does language switching edit my records?

It must not; locale selection should alter presentation without mutating stored values. In practice, start with one complete user task and validate both the words and what the interface does. The right answer depends on the framework and integration version, the supported platform, and the actual languages promised to readers. Avoid changing stored identifiers or user content to solve a display-only problem.

How do I test multilingual releases?

Install production packages in clean OS environments and exercise real forms, data, warnings and keyboard navigation. In practice, start with one complete user task and validate both the words and what the interface does. The right answer depends on the framework and integration version, the supported platform, and the actual languages promised to readers. Avoid changing stored identifiers or user content to solve a display-only problem.

Official documentation and further reading

Documentation is the best place to verify library-specific signatures and dependency compatibility. Examples in this guide describe the implementation pattern rather than guaranteeing that one API spelling remains valid in every release. Consult the linked official reference for your pinned version before you compile or distribute code, especially when combining a UI framework with an independent localization crate.

Continue learning about trustworthy translation

This article focuses on Lazarus LCL implementation and packaged interface tests, not a replacement for general translation knowledge. If you need to understand how meaning, evidence, uncertainty and social context survive a language change, read the translation master guide. For another framework, follow the series index instead of mixing unrelated APIs in one solution.

Master Art of Translation: complete system · Translate Like a Pro series index · eduKateSG longform reference · Previous article in this series

Translate Like a Pro | 7350 — Lazarus Free Pascal LCL Localization, PO Files, ResourceStrings, DefaultTranslator and Cross-Platform QA