How do you translate an OutSystems 11 Reactive Web or Mobile app and make its language switcher work without misrepresenting the data behind the interface? This OutSystems multilingual app guide explains Multilingual Locales, the Service Studio translation editor, SetCurrentLocale, GetCurrentLocale, static-entity translations, client and server behavior, and meaningful release testing.
OutSystems 11 documentation describes language support for Reactive Web and Mobile Apps, including adding locales in Service Studio, editing translated strings and using a client action to change the current locale. It also identifies differences between Reactive and Traditional Web Apps, notes that the current locale is associated with the user session, and explains additional handling for static-entity translations. These details matter because an older tutorial or an unrelated OutSystems development model may expose different steps.
The point of localization is that someone can read a page, choose an action, make an informed decision and understand the real outcome in their language. A translated screen can still be unreliable if a validation message remains in another language, a data refresh is missing or the app reports success before the backend does. This chapter offers a platform-specific route from setting up locales to testing complete customer journeys.
Quick answer
For OutSystems 11 Reactive Web and Mobile Apps, add supported locales under Multilingual Locales in Service Studio, translate the necessary resources and implement a visible language switcher with the documented SetCurrentLocale Client Action where appropriate. Define locales in relevant modules, check current-locale behavior with GetCurrentLocale, refresh static-entity data when necessary and test actual sessions, logouts, errors and permissions. Do not apply Traditional Web instructions uncritically to Reactive apps.
Before you begin: a practical checklist
- Confirm the app is OutSystems 11 Reactive Web or Mobile, not Traditional Web or another platform.
- Review Service Studio and Platform Server versions against the documentation.
- Add locales deliberately and record exact language codes.
- Translate all relevant app modules, not one screen only.
- Implement and test SetCurrentLocale Client Action for user selection.
- Check Static Entity translation setup and data refreshing.
- Test session, logout, errors, mobile layouts, accessibility and the backend outcome.
- Keep public search-page localization separate from private-app interface translation.
Why this platform needs its own translation plan
OutSystems brings together UI resources, locale selection, session behavior, client actions and static data. When these parts are understood separately, the translation workflow is straightforward. When they are confused, a user may see mixed languages, stale labels or a different state after a locale switch. Work from the actual OutSystems 11 Reactive app and validate each action against the platform’s current documentation, not assumptions borrowed from Traditional Web modules.
1. Confirm the correct OutSystems platform and app model
OutSystems publishes distinct guidance for OutSystems 11 Reactive Web and Mobile Apps and for Traditional Web Apps. The documentation for Reactive and Mobile multilingual support specifies Platform Server 11.12.0 or later and up-to-date Service Studio.
A practical example
A developer searches for a language tutorial and lands on an older Traditional Web article with different export menus and locale behavior.
The common mistake is this: Following the wrong application model can create confusing instructions or false expectations even if some general terms sound familiar.
A reliable way to handle it: Identify the platform edition, module type and versions first; use the Reactive and Mobile documentation for the corresponding task.
Evidence to inspect: Record the version and the exact UI features visible in the current project before changing language resources.
A useful translation review follows the meaning of an action all the way into system state. The important question is not whether a label has a counterpart in another language. It is whether the person understands the same choices, conditions and consequences in both versions.
2. Know what Multilingual Locales controls
OutSystems 11 Service Studio exposes Multilingual Locales under the Data tab for supported language resources. Adding a locale prepares the module for translated UI text, but is only one step in the full app experience.
A practical example
A support portal adds pt-BR as a locale yet continues to show untranslated validation text in two modules.
The common mistake is this: A successful Add Locale operation may be mistaken for completion of every visible message across the application.
A reliable way to handle it: Add the intended locales and enumerate all modules that contribute user-visible text; review resource coverage rather than just the locale list.
Evidence to inspect: Open real screens and trigger conditional messages in each locale, ensuring that their text matches the intended meaning.
A screen can look finished while the journey remains unfinished. Check the step before and after the translated element, including the results of invalid input and a return visit. Language quality becomes visible when the application must explain what happened.
3. Use the Service Studio translation editor
OutSystems documentation describes selecting resources in the translation editor and choosing Translate where a resource should receive localized text. This applies to interface items such as screen titles, buttons and messages.
A practical example
A public transport app has a translated route heading but an untranslated Cancel button and an untranslated delay notice.
The common mistake is this: The translator may fill obvious headings while leaving operational messages hidden behind event triggers.
A reliable way to handle it: Inspect the editor’s translation behavior and work through important resources in context, including screens, links, validation and human activity instructions.
Evidence to inspect: A reader in the target language can understand every step from the entry screen to the real task result.
Stable records and stable permissions are essential. The user’s language may change the explanation of an invoice, order or request, but it should not silently create a new invoice, modify the amount or alter access rights. Check the backend outcome, not only presentation.
4. Translate across all participating modules
An application can combine UI modules, reusable components and shared elements. OutSystems explicitly advises translating text in all modules of an app, not just the module currently open.
A practical example
A multilingual checkout page uses a shared address component that still displays its original English error messages.
The common mistake is this: An interface appears half-translated because the shared module was never included in the resource inventory.
A reliable way to handle it: List modules and reusable components used in the journey, assign language review responsibility and validate them as part of the assembled app.
Evidence to inspect: The same component displays a coherent target-language experience wherever it is reused.
Avoid inferring production behavior from an editor preview or a translation percentage. A real release may include cached client state, messages from another module or an unexpected error path. Evidence must come from running the actual workflow and checking the server result.
5. Remember the documented default and session behavior
OutSystems 11 multilingual Reactive and Mobile guidance states that its default language code is en-US and the current language is tied to a user session. After logout, the language code resets to the default in the documented behavior.
A practical example
A user chooses German in a secure portal, logs out and returns to the public sign-in page in English.
The common mistake is this: A team promises that a language preference will persist forever simply because it worked during one authenticated session.
A reliable way to handle it: Test logout and new-session behavior. If the product needs persistent preference beyond the built-in session rule, design that requirement explicitly and verify it.
Evidence to inspect: The user is not surprised by an undocumented language change and can select an available language again.
Translation is an ongoing maintenance duty. Every new widget, validation rule and business state introduces potential new language. Put language review into ordinary product change management so that one careful release does not decay into inconsistent experiences.
6. Use exact locale codes and case with care
The OutSystems Reactive documentation notes that language codes are case sensitive and that selectable codes are influenced by the operating system environment. A language identifier should be treated as configuration, not a casually formatted label.
A practical example
An app configures pt-BR but a client action passes an inconsistent spelling or case.
The common mistake is this: The intended translation can fail to appear while the app silently falls back or displays the default text.
A reliable way to handle it: Copy the supported locale code from the project’s configured locale, use it consistently and test every language selector choice.
Evidence to inspect: After selection, GetCurrentLocale and the visible UI agree with the expected language.
A reasonable fallback is honest, not invisible at any cost. An understandable default is better than an empty interface, but a high-risk statement must not be misrepresented as translated or approved when it is not. Record limitations where they affect decisions.
7. Build a clear language switcher
The OutSystems guide shows that a Link, Button or Dropdown can be used to let a person choose a language, with an On Click Client Action invoking SetCurrentLocale.
A practical example
A customer chooses Spanish from a visible dropdown and expects the present screen and subsequent navigation to use Spanish.
The common mistake is this: A dropdown that merely changes its own label does not update the application locale, and a hidden switcher leaves users unable to recover.
A reliable way to handle it: Create the appropriate Client Action, supply a configured locale and test the effect on navigation and displayed resources.
Evidence to inspect: The selected locale matches the intended language and the next screen remains coherent.
A useful translation review follows the meaning of an action all the way into system state. The important question is not whether a label has a counterpart in another language. It is whether the person understands the same choices, conditions and consequences in both versions.
8. Prefer the documented client action in appropriate contexts
The official guide specifically says SetCurrentLocale Server Action does not work offline and recommends using the Client Action where possible for Reactive or Mobile flows.
A practical example
A mobile worker changes language while the application is temporarily disconnected from the network.
The common mistake is this: A server-only language switch may fail during offline use or give the impression that language changes require connectivity.
A reliable way to handle it: Use the documented Client Action for suitable interface workflows; test online, offline and reconnection behavior with realistic app state.
Evidence to inspect: The visible locale updates as intended and no queued business action is mistakenly reported as complete.
A screen can look finished while the journey remains unfinished. Check the step before and after the translated element, including the results of invalid input and a return visit. Language quality becomes visible when the application must explain what happened.
9. Define locale where client and server must agree
OutSystems states that SetCurrentLocale and GetCurrentLocale can persist across client and server requests only when the locale is defined at module level.
A practical example
A flow displays an Italian screen correctly but the subsequent server-generated response uses the default language.
The common mistake is this: A locale choice visible in one component does not necessarily mean every server or module action recognizes it.
A reliable way to handle it: Confirm the module has the required locale definitions and test client-server boundaries in the actual workflow.
Evidence to inspect: Both a locally rendered label and a server-dependent message represent the same intended locale.
Stable records and stable permissions are essential. The user’s language may change the explanation of an invoice, order or request, but it should not silently create a new invoice, modify the amount or alter access rights. Check the backend outcome, not only presentation.
10. Understand GetCurrentLocale before making decisions
OutSystems exposes GetCurrentLocale for querying the current locale. The value can help choose suitable display resources, but it is not proof of user identity, region or eligibility.
A practical example
A public app uses the current locale to select Italian UI labels and then incorrectly assumes the user is legally resident in Italy.
The common mistake is this: Language preference and residence, currency or access rights are different facts; conflating them can cause major errors.
A reliable way to handle it: Use GetCurrentLocale for its documented language purpose. Collect other required attributes through the appropriate application process.
Evidence to inspect: Business logic continues to use authenticated facts and verified policies, not an inferred nationality from language code.
Avoid inferring production behavior from an editor preview or a translation percentage. A real release may include cached client state, messages from another module or an unexpected error path. Evidence must come from running the actual workflow and checking the server result.
11. Translate Static Entities with special care
OutSystems 11 documents a separate procedure for translated Static Entity text, and notes that text identifiers in Static Entities cannot be translated. Visible labels and underlying identifiers serve different purposes.
A practical example
A request form displays a translated category name but still submits the canonical category identifier.
The common mistake is this: Trying to translate identifiers would damage relationships, filters and reporting even if the display appears correct.
A reliable way to handle it: Translate supported visible text resources while leaving the machine identifiers stable and reviewing how the UI consumes them.
Evidence to inspect: The selected category has the same identifier across locales and its label is accurate in each.
Translation is an ongoing maintenance duty. Every new widget, validation rule and business state introduces potential new language. Put language review into ordinary product change management so that one careful release does not decay into inconsistent experiences.
12. Refresh data after changing locale where required
The official translation guide instructs adding Refresh Data after SetCurrentLocale when the screen uses translated Static Entity values. The UI and its data source must be synchronized.
A practical example
A form switches from English to German but a dropdown populated from a Static Entity still shows English option labels.
The common mistake is this: The language selector appears broken even though the configured string resources are valid.
A reliable way to handle it: Add and test the appropriate Refresh Data action and inspect any dependent queries or widgets after switching locales.
Evidence to inspect: All options are refreshed into the target language without changing their coded values or the user’s valid selection.
A reasonable fallback is honest, not invisible at any cost. An understandable default is better than an empty interface, but a high-risk statement must not be misrepresented as translated or approved when it is not. Record limitations where they affect decisions.
13. Distinguish translation resources from application records
OutSystems translation tools cover UI resources and designated Static Entity text. A database table full of article paragraphs or customer comments requires a separate multilingual content strategy.
A practical example
A travel catalog switches button language but still displays its source-language descriptions fetched from an external API.
The common mistake is this: A completed translation editor can be mistaken for automatic translation of arbitrary stored business content.
A reliable way to handle it: Create a governed content model or locale-aware API for records that require human translations; keep provenance and stable IDs.
Evidence to inspect: The same item displays accurate translated descriptions while inventory, ratings and permissions remain consistent.
A useful translation review follows the meaning of an action all the way into system state. The important question is not whether a label has a counterpart in another language. It is whether the person understands the same choices, conditions and consequences in both versions.
14. Keep transaction states authoritative
Words such as Requested, Received, Approved and Completed describe different stages of a workflow. Localization must not compress them into one optimistic success message.
A practical example
An employee files an expense claim and sees a translated ‘approved’ notice even though the backend has merely accepted a draft.
The common mistake is this: That false promise can affect financial decisions and accountability despite a fluent sentence.
A reliable way to handle it: Map each status to an actual state transition, translate complete messages and test success, pending and rejected paths.
Evidence to inspect: The translated text always reflects the authoritative server status of the specific request.
A screen can look finished while the journey remains unfinished. Check the step before and after the translated element, including the results of invalid input and a return visit. Language quality becomes visible when the application must explain what happened.
15. Handle validation and empty states as seriously as headings
OutSystems documents validation, widget confirmation and empty messages among translatable resources. These often become visible only when the user encounters a problem.
A practical example
A second-language user submits an incomplete registration form and receives a default-language explanation of mandatory fields.
The common mistake is this: The user cannot safely fix an error if the message fails to identify the required correction or appears in an unfamiliar language.
A reliable way to handle it: Trigger invalid data, no-results cases and confirmation prompts in each locale. Ask in-language readers to explain what they must do next.
Evidence to inspect: Users distinguish between invalid input, missing results and successful submission without guessing.
Stable records and stable permissions are essential. The user’s language may change the explanation of an invoice, order or request, but it should not silently create a new invoice, modify the amount or alter access rights. Check the backend outcome, not only presentation.
16. Do not confuse switching locales with regional policy
A language code such as fr-FR can guide wording and formatting, but it does not establish tax residence, service eligibility or the correct payment currency.
A practical example
A visitor chooses French while making a service request from another country.
The common mistake is this: A system that changes prices or entitlements solely because of the language selector risks inaccurate terms and unfair treatment.
A reliable way to handle it: Use verified user or transaction data for business rules; format dates and numbers appropriately while retaining the correct source values.
Evidence to inspect: The reader sees understandable language without unexpected changes to price, eligibility or account access.
Avoid inferring production behavior from an editor preview or a translation percentage. A real release may include cached client state, messages from another module or an unexpected error path. Evidence must come from running the actual workflow and checking the server result.
17. Review date, number and time meaning
Translating a button label does not guarantee that a date, decimal separator or cutoff time is understood correctly. For regional use, formatting rules must be inspected alongside the translated sentence.
A practical example
A deadline is 18:00 UTC, but the screen says ‘today at six’ without identifying the relevant time zone.
The common mistake is this: An ambiguous time can cause missed appointments even when the translation grammar is perfect.
A reliable way to handle it: Define timestamp ownership, apply appropriate formatting and show the zone for consequential deadlines. Compare with the backend record.
Evidence to inspect: Testers in different regions can state the same real deadline using their local conventions.
Translation is an ongoing maintenance duty. Every new widget, validation rule and business state introduces potential new language. Put language review into ordinary product change management so that one careful release does not decay into inconsistent experiences.
18. Respect RTL and mixed-direction content
Right-to-left languages can require more than translated text. Navigation, alignment, icons and mixed Latin identifiers may need additional layout testing.
A practical example
An Arabic service app shows a left-to-right tracking number embedded inside right-to-left instructions.
The common mistake is this: Blindly mirroring all characters can corrupt an exact identifier that must be copied into a support request.
A reliable way to handle it: Test native or browser layout direction as supported, ensure important controls stay discoverable and protect structured IDs from visual confusion.
Evidence to inspect: Readers can navigate, identify status and copy tracking codes correctly.
A reasonable fallback is honest, not invisible at any cost. An understandable default is better than an empty interface, but a high-risk statement must not be misrepresented as translated or approved when it is not. Record limitations where they affect decisions.
19. Make accessibility part of the locale test
Translated visible captions are not enough if screen-reader names, focus hints or error announcements remain in another language. Accessibility affects whether a person can complete a task at all.
A practical example
A user with low vision relies on a screen reader that announces a translated button using an outdated English accessibility label.
The common mistake is this: A visual design review can miss a broken interaction path for users who cannot inspect the screen visually.
A reliable way to handle it: Test keyboard focus, screen readers, enlarging text and important error announcements in each language where feasible.
Evidence to inspect: Assistive-technology users can identify actions and recover from errors without receiving contradictory labels.
A useful translation review follows the meaning of an action all the way into system state. The important question is not whether a label has a counterpart in another language. It is whether the person understands the same choices, conditions and consequences in both versions.
20. Keep authorization entirely separate from language
The current locale is an interface setting, not permission to view records. A properly designed OutSystems app must enforce account-based access rights regardless of language.
A practical example
Two workers use the same app with different languages and roles; switching locale must never reveal another worker’s private records.
The common mistake is this: A poorly constructed query that conflates locale with account filtering can create security defects.
A reliable way to handle it: Run two-account permission tests and verify server-side rules for all data endpoints and locale states.
Evidence to inspect: The same record is authorized or forbidden under identical business rules in every language.
A screen can look finished while the journey remains unfinished. Check the step before and after the translated element, including the results of invalid input and a return visit. Language quality becomes visible when the application must explain what happened.
21. Plan translated notifications and external artifacts
Email, external PDFs, API messages and push alerts may use separate systems and templates. Service Studio UI translations should not be described as controlling every downstream communication.
A practical example
An account is updated through a Spanish app, but the attached PDF and follow-up email use English terms and incompatible date notation.
The common mistake is this: This gap can make a correct interface feel untrustworthy when the user needs a record of what happened.
A reliable way to handle it: Inventory external communications and documents, identify their owners and test them after an actual workflow event.
Evidence to inspect: The visible status, document and notification all describe the same authoritative event.
Stable records and stable permissions are essential. The user’s language may change the explanation of an invoice, order or request, but it should not silently create a new invoice, modify the amount or alter access rights. Check the backend outcome, not only presentation.
22. Build a release-specific regression plan
A new module or interface action can introduce fresh resources, state changes and unexpected language fallbacks. Test the complete app after changes, not only the resource file affected.
A practical example
A new approval step appears in the purchase workflow and the old translations still describe the first step as completion.
The common mistake is this: Teams may ship a syntactically complete translation that makes a newly changed business promise inaccurate.
A reliable way to handle it: Maintain an acceptance matrix for module, locale, user role, connectivity, invalid input and actual outcome. Update it after product changes.
Evidence to inspect: The shipped build supports the same task outcomes and precise status meanings across tested locales.
Avoid inferring production behavior from an editor preview or a translation percentage. A real release may include cached client state, messages from another module or an unexpected error path. Evidence must come from running the actual workflow and checking the server result.
Hands-on acceptance tests for teams
1. The Reactive versus Traditional distinction
Open the project in Service Studio and identify its Reactive Web or Mobile type before finding multilingual controls.
Compare the actual project model with OutSystems 11 guidance and avoid copying an export workflow from the Traditional Web section.
The intended result is specific: The team uses documented instructions appropriate to the app they are shipping.
Repeat this exercise on a clean account and a returning account. Use the same business record, one source language and one target language; keep a record of the locale, app version, action, actual result and where the observed behavior differs.
2. The first switch to pt-BR
Add an approved pt-BR locale and implement a clearly labeled Client Action that calls SetCurrentLocale.
Use the exact configured code, switch to Portuguese and inspect GetCurrentLocale and the visible captions on the next screen.
The intended result is specific: The interface and locale state correspond to the intended language.
Run the same test with incomplete or invalid input. Compare the language shown in an error, the state held by the app, and the authoritative server record. A fluent success notice is not evidence of success unless the server agrees.
3. The translated Static Entity dropdown
Create a dropdown with translated Static Entity text and select one value before changing languages.
Add the documented data refresh after locale switch, confirm displayed labels update and ensure the selected code remains unchanged.
The intended result is specific: The control shows the new language without changing the user’s selected category.
Repeat this exercise on a clean account and a returning account. Use the same business record, one source language and one target language; keep a record of the locale, app version, action, actual result and where the observed behavior differs.
4. The logout reset
Choose a target language during a signed-in session, log out and start a fresh session.
Observe and document the platform’s default-language reset and provide a clear recovery path for users who wish to select the target again.
The intended result is specific: The language behavior is predictable rather than an unexplained product defect.
Run the same test with incomplete or invalid input. Compare the language shown in an error, the state held by the app, and the authoritative server record. A fluent success notice is not evidence of success unless the server agrees.
5. The offline mobile path
Switch language in a mobile context when a simulated network outage prevents a server response.
Use the documented client-action approach where appropriate and separate local UI translation from deferred backend operations.
The intended result is specific: The user can understand the interface but is not falsely told that an offline submission completed.
Repeat this exercise on a clean account and a returning account. Use the same business record, one source language and one target language; keep a record of the locale, app version, action, actual result and where the observed behavior differs.
6. A cross-module translation gap
Build a journey using a shared component from a different OutSystems module.
Check that the module’s resources and relevant locales are configured and translated; trigger its validation messages.
The intended result is specific: Shared components do not unexpectedly revert to the default language.
Run the same test with incomplete or invalid input. Compare the language shown in an error, the state held by the app, and the authoritative server record. A fluent success notice is not evidence of success unless the server agrees.
7. A status challenge
Submit an approval request and simulate accepted, pending and rejected outcomes.
Compare user-visible translations against the actual backend state and keep status identifiers invariant.
The intended result is specific: Each translated message states the real stage of the request.
Repeat this exercise on a clean account and a returning account. Use the same business record, one source language and one target language; keep a record of the locale, app version, action, actual result and where the observed behavior differs.
8. A long-string and RTL screen
Inspect one narrow screen with an expanded translated label and a right-to-left script where supported.
Test touch targets, focus movement, mixed-direction identifiers and the actual navigation sequence with readers of the language.
The intended result is specific: The interface remains usable and structured identifiers stay intact.
Run the same test with incomplete or invalid input. Compare the language shown in an error, the state held by the app, and the authoritative server record. A fluent success notice is not evidence of success unless the server agrees.
9. An authenticated access check
Use accounts with different record ownership and repeat an API-backed page in two languages.
Verify authorization independently of GetCurrentLocale and any presentation label. Deliberately attempt a record owned by the other account.
The intended result is specific: Language selection never changes which private resources the user may access.
Repeat this exercise on a clean account and a returning account. Use the same business record, one source language and one target language; keep a record of the locale, app version, action, actual result and where the observed behavior differs.
A four-week rollout readers can follow
Week 1: Verify the app model
Identify OutSystems 11 Reactive or Mobile modules, actual versions, languages and user journeys. Map text resources, Static Entities, API content and communications that sit outside the translation editor.
Record default and target locale codes and decide how the language selector will appear to users.
Week 2: Build the bilingual pathway
Configure Multilingual Locales in relevant modules, translate critical texts and use SetCurrentLocale Client Action appropriately. Implement Static Entity data refresh where needed.
Run a complete request journey in the new locale, including a selected dropdown value and the server-confirmed outcome.
Week 3: Exercise failure modes
Test offline behavior, session and logout changes, cross-module resources, empty states, invalid input, long strings, privacy boundaries and accessibility.
Confirm where client/server locale persistence is documented and measure the behavior in the shipped app rather than inferring it.
Week 4: Release with a maintenance plan
Review all user-visible modules, external notifications and task states. Check localized claims against server results and provide documented fallback or language-selection routes.
Assign owners to new translation resources whenever the app adds workflows or modules; retain evidence from both locales.
Frequently asked questions
Does this guide apply to every OutSystems product?
No. It focuses on OutSystems 11 Reactive Web and Mobile multilingual features. Traditional Web and other platform models have different documentation and may require different steps.
Where do I add locales?
OutSystems 11 Service Studio documents Multilingual Locales under the Data tab. Check the platform version and the relevant modules.
How do I change the current language?
The official guide shows a user-facing control whose Client Action invokes SetCurrentLocale with a configured locale code.
Why does a translated dropdown stay in the old language?
Static Entity translations may need their data refreshed after SetCurrentLocale, as described in the official documentation.
Does SetCurrentLocale work offline?
The documentation cautions that the Server Action does not work offline and recommends the Client Action when possible.
What happens to locale after logout?
The OutSystems 11 Reactive and Mobile guide describes locale being bound to the session and resetting to the default after logout.
Can translated Static Entity identifiers change?
They should not. The platform states that text identifiers in Static Entities cannot be translated; localize display wording, not machine identity.
Does GetCurrentLocale prove the user’s country?
No. It identifies current language context, not citizenship, residence, legal eligibility or other verified regional facts.
Is every API record automatically translated?
No. UI resources and designated Static Entity text are distinct from arbitrary backend and external content.
What is a convincing final test?
An independent target-language user completes the same task as a default-language user, and the verified status, permissions and record IDs remain correct.
The standard worth aiming for
A good OutSystems 11 multilingual app lets a person choose a language, follow coherent screens and act on trustworthy information. Static Entities, translation resources, client actions and session behavior work together without changing the transaction’s truth. When users can finish a real task and the backend agrees with what the interface says, the translation has done its job.