CAP localized texts: Check locale, translations and fallback before copying data
A manufacturer serves component descriptions to users at factories with different languages, while some translations are missing.
START HERE · NO PRIOR TOPIC KNOWLEDGE NEEDED
What it is. Why it matters.
Localized texts store language-specific descriptions. SAP CAP can select a suitable translation using the request’s language context and its supported fallback behavior.
Completely new to SAP?
Manufacturers use SAP to connect work such as buying components, recording inventory, planning production, shipping equipment and accounting for costs. SAP S/4HANA is an enterprise resource planning system: it connects these activities through shared business data.
ABAP is SAP’s programming language for business applications. A program reads data, applies rules and produces a result. Start with the objects involved before investigating code.
A transaction code, or t-code, is a shortcut to a task in classic SAP GUI. Fiori apps provide another way to work. Names and screens depend on the product and release; you do not need a live system to learn the concepts in this guide.

Scope and source-review notes
Scope and evidence
Source review by FAST SAP SOLUTIONS® editorial. This badge describes our editorial review; it does not represent SAP certification or independent endorsement.
CAP localized application data and normalized request locales; database adapters, drafts and default-language behavior require installed-version verification.
Primary documentation reviewed on 14 November 2026 using readable full text and official indexed excerpts. Relevant full-text CAP localization sections reviewed; May 2025 compatibility change reviewed through indexed release notes. Illustrative model/requests were not compiled or run against a deployed adapter.
A MANUFACTURING EXAMPLE
Explain component descriptions across languages
Follow the requested language
Read the example values
- Requested language
- French
- Available translation
- English only
- Product description
- Language-dependent
- Review
- Supported fallback behavior
Words you’ll meet in this guide
- Program
- A set of instructions executed by a computer.
- Class
- A reusable unit that groups data with operations called methods.
- Database
- Organized information kept beyond one program execution.
- Internal table
- A list of rows held temporarily in an ABAP program’s memory.
- Key
- One or more fields used to identify or find a record.
- CDS
- Core Data Services: reusable definitions of business data and relationships.
Preview the practical steps
SEE THE CONNECTION
See it in a simple example.
A small example to make the idea concrete.
Explain component descriptions across languages
A manufacturer serves component descriptions to users at factories with different languages, while some translations are missing.
Localized business data and UI label bundles are different text paths
When a product title stays in the default language, inspect the localized data model, effective request locale and translation row.
Scope and prerequisites
The guide covers current CAP localized entity elements and request-locale concepts for Node.js and Java.
Understand the generated relationship
A localized String element tells CAP that a business text can have translations.
Explain component descriptions across languages
A manufacturer serves component descriptions to users at factories with different languages, while some translations are missing.
Compare requested locale, available localized text and documented fallback behavior before treating an unexpected language as a missing product.
| Reader | Business question | Evidence to carry forward |
|---|---|---|
| SAP developers and application teams supporting manufacturers | Explain component descriptions across languages | Compare requested locale, available localized text and documented fallback behavior before treating an unexpected language as a missing product. |
01 Localized business data and UI label bundles are different text paths
When a product title stays in the default language, inspect the localized data model, effective request locale and translation row. A translated page heading does not prove the business data was localized. CAP's static i18n bundles serve labels and messages; localized entity elements hold language-specific application text under one stable business identity. [1] [2]
Missing translation can correctly produce fallback text. A wrong locale, wrong translation key, disabled localization or custom raw read can produce a similar screen. This tutorial uses two fictional products to distinguish those mechanisms before changing data or duplicating business records.
02 Scope and prerequisites
The guide covers current CAP localized entity elements and request-locale concepts for Node.js and Java. Compiler, runtime and database adapters evolve; record their installed versions and check matching release notes. Draft processing, custom handlers and database-specific localization support need separate validation in the actual project.
You need access to the CDS model, a small base/translation fixture and sanitized service responses. You do not need to copy all business data into another language-specific table manually. The model and requests below are illustrative. They have not been deployed or executed against a customer CAP application, and an empty translation is treated deliberately rather than assumed equivalent to a missing row.
03 Understand the generated relationship
A localized String element tells CAP that a business text can have translations. The model is unfolded into a texts entity keyed by locale and the source identity, with associations for all texts and the current localized text. The base entity retains its original/default text rather than externalizing every value. [1]
The documented localized view concept uses a fallback expression such as coalesce(translated_title, base_title). A missing translated value can therefore fall back to the base text. An empty string is a value, however; do not assume it triggers the same null fallback. Translation maintenance should define whether an intentionally blank label is allowed and how incomplete translations are represented. [1]
04 Worked case: two products with partial French coverage
Fictional Products contains ID 101 titled Safety valve and ID 102 titled Pressure gauge. The texts dataset contains French title Soupape de sécurité for 101 but no French row for 102. A localized French read should show the French title for 101 and the base title for 102 under the documented per-row fallback model.
Both products retain the same IDs and prices across locales. Creating a second product 201 for the French version would split business identity and complicate orders, stock and reporting. Translation is a dependent text dimension, not a reason to duplicate the product master. A list can legitimately contain one translated title and one fallback title when translation coverage is incomplete.
| Product ID | Base title | French translation | Expected French display |
|---|---|---|---|
| 101 | Safety valve | Soupape de sécurité | Soupape de sécurité |
| 102 | Pressure gauge | No translation row | Pressure gauge |
| 103 boundary | Control unit | Empty string | Check explicit blank-text policy |
05 Model localized elements and expose a suitable projection
The small CDL sketch retains the business key and marks title as localized. Expose a service projection that preserves the necessary localized semantics. Expressions, aliases or custom projections can require attention to annotation/type propagation; inspect the compiled model and generated service behavior instead of assuming every calculated string remains localized.
Keep the translation-maintenance path separate from the end-user read. The to-many texts relationship is useful to inspect all maintained languages, while the localized result is intended to select a suitable text for one request. Expanding all translation rows into every list item is not a replacement for a clear localized service contract.
namespace demo;
entity Products {
key ID : Integer;
title : localized String(100);
price : Decimal(9,2);
}06 Observe the effective locale rather than guessing from the browser
Current CAP localization documentation describes request-language determination and normalization. URL locale parameters can take precedence over Accept-Language. Locale variants can be narrowed or preserved according to runtime configuration, so a browser set to French Canada does not establish that the translation lookup key is exactly fr_CA in every project. [2]
For diagnosis, hold the product identity fixed and issue explicit, authorized requests with a known language header or supported locale parameter. Inspect the resolved request locale in the handler where appropriate, such as req.locale for Node.js. Record only the locale and fixture identity needed for the investigation. Avoid logging an unrestricted request or authentication context. [1]
GET /odata/v4/catalog/Products?$select=ID,title HTTP/1.1
Accept-Language: fr
Expected teaching result:
101 -> Soupape de sécurité
102 -> Pressure gauge (base fallback)07 Compare translation keys with normalization rules
Translation identity includes the product key and locale. A French row attached to product 201 cannot translate product 101. A region-specific locale stored under a differently normalized identifier may also fail to match. CAP documents underscore-normalized locale storage conventions, while incoming language tags commonly use hyphens. [2]
Inspect actual normalized locale and maintained text keys before renaming records. Do not indiscriminately replace every regional variant with a base language; some variants are intentionally preserved and can have distinct wording. Keep runtime configuration, translation files and database LOCALE values consistent. A single successful fr request does not prove a separately configured fr_CA request follows the same selection path.
08 Distinguish generic localized reads from custom raw access
Generic service handling can select localized data, but a custom handler may query the underlying base entity directly or return a handcrafted payload. That can intentionally or accidentally bypass the expected localized result. Trace whether the custom code returns title from the base source, a localized association or another remote service.
Also inspect explicit localization-disabling annotations and draft-specific behavior in the installed runtime. The CAP guide documents @cds.localized: false for direct base access. If base-language text is deliberate for an administration view, preserve that intent rather than “fixing” it globally. End-user and translation-maintenance services can validly expose different text views. [1]
09 Troubleshooting fallback and missing translations
Compare model, locale, stored key and service response before looking at the UI formatter. If the payload is already correct, a stale client cache or another binding becomes a separate frontend question.
| Observation | Question | Next check |
|---|---|---|
| All titles remain base language | Is effective locale resolved and localization enabled? | Request locale, projection and annotations |
| Only product 102 uses base text | Is its French translation missing? | texts row for ID 102 and fr |
| Translation exists but not selected | Key or normalized locale mismatch? | Actual ID/LOCALE pair |
| Title unexpectedly blank | Empty string versus null/missing? | Stored translated field and blank policy |
| Generic read works; custom endpoint does not | Raw query or custom payload bypass? | Handler source and result mapping |
| Backend French; screen English | Wrong model/cache/binding? | Network payload and UI binding |
| After runtime upgrade behavior changes | Locale/default behavior changed? | Installed release notes and regression fixture |
10 Maintain translations through a supported service contract
Use the documented texts composition/navigation or a dedicated translation-maintenance workflow supported by the application. Keep the base ID stable and maintain one intended locale row per identity. Validate length and required text rules where business users need complete translations. Do not update a localized display string and assume it automatically changes every language.
A base-text update can affect fallback users while leaving explicit translations unchanged. That is often desirable, but it needs an editorial process: an older French description may become inaccurate after the base product wording changes. Record translation completeness and ownership separately from technical fallback. Fallback keeps a service usable; it does not certify language quality.
A useful maintenance experiment changes only one dependency at a time. Read product 102 in French and confirm base Pressure gauge. Add its supported French text row, keeping ID 102 and price unchanged, then read again and expect the maintained French wording. Remove that test row through the supported workflow and expect base fallback again. This distinguishes translation coverage from the product's existence and avoids confusing an unrelated UI deployment with a data correction.
Next change the base title of product 101 in a disposable fixture while preserving its explicit French translation. Compare base-language and French responses: the fallback population can see the new base wording while the maintained French text remains independently owned. Review that difference with the translation owner. For every observation, keep the effective locale, ID, base value, translation value and returned value together; a screenshot of a French heading supplies none of that data-path evidence.
11 Verify mixed lists, nulls and regional locales
A positive check requests fr and expects the translated title for 101. A negative/missing-coverage check expects the documented base fallback for 102 while confirming the product still exists. A boundary check adds a deliberately blank translation and observes its actual result under the chosen blank-text policy.
Repeat with the base language, no explicit locale and a configured regional locale. Compare runtime behavior after dependency upgrades because default-language handling has changed in some CAP releases. Verify one detail read, a mixed list, search/sort behavior required by the app and any relevant expanded association. Check identity and price remain unchanged. These are proposed checks; this article does not claim runtime validation.
12 Frequently asked questions
Why is the page heading French but the product title English? The heading may come from an i18n bundle while the title is localized business data with missing translation or another read path.
Should I add a second product for each language? No. Preserve the business identity and maintain dependent localized texts under the supported model.
Does a missing translation mean a missing product? No. Verify the base entity separately; per-row fallback can return its original text.
Can I rely on browser language alone? Inspect the effective normalized request locale and configuration. URL parameters, runtime rules and preserved regional variants can change the lookup key.
What makes a useful handoff? Include one product ID, base text, translation row/locale, effective request locale, service response and the first boundary that differs from expectation.
Related services and next steps
Primary sources
Found this useful?
Share this guide with your network, or leave a like.
Your like is saved in this browser.