To translate a web application manifest quickly, preserve the application’s id, start_url, scope, icon URLs and shortcut destinations, then provide reviewed localized names and descriptions in the fields supported by the chosen manifest specification and browsers. Test the app after installation, not only while reading the JSON file. The visible name on a home screen, the short label under an icon, and the shortcuts a person selects are separate pieces of copy; none should cause the installed application to become a different app or launch a different destination.
A search for web app manifest localization, PWA installed app name translation, or name_localized shortcut QA now leads to an important version distinction. The W3C Web Application Manifest Working Draft dated 26 October 2026 describes *_localized language maps for certain manifest members. It is a Working Draft rather than a stable Recommendation, and individual browsers may support only part of it. Responsible localization therefore separates the proposed data model from verified device behavior and supplies a fallback instead of promising universal support.
This guide explains what to translate in an installable web app, what must remain immutable, how default names interact with localized variants, how manifest language and direction affect labels, and how to test launch behavior across devices. It includes a small JSON fixture, failure diagnostics, a changed-context exercise and its answer, a practical checklist and ten questions. The intended reader is a developer, designer or educator maintaining a multilingual app, not someone editing a browser extension’s _locales message files.
Start with what the user sees after installation
Imagine a school homework planner that runs in a browser but can also be installed on a phone. In English its home-screen icon says “Planner”; a student using Simplified Chinese should see a suitable short name and understand the “Today’s tasks” shortcut. Changing the website’s language switcher alone may not update the installed icon label. The manifest provides installation metadata consumed by the browser or operating system, and that interface can have its own caching, lifecycle and localization behavior.
Begin by listing the exact visible surfaces: installation prompt title, installed home-screen name, truncated short name, shortcut names, any shortcut descriptions, icons and launch destination. Confirm which surfaces the target browser actually derives from manifest data. Some products substitute platform-specific conventions or defer updates. Without this inventory, a team may declare the page translated while the installed app still looks English or launches the wrong task. The job is the experience a user receives, not the presence of translated strings in a repository.
Define a minimum acceptance test before work begins. On supported browsers, the selected locale should display the approved app name and shortcuts; on browsers without localized-member support, a meaningful default should remain; installing or updating should not create unintended duplicate apps; all shortcuts should reach the original authorized destinations. Record device, browser version, manifest URL, language preferences and installation state. These facts are essential because two testers can obtain different results from identical JSON when platform support or cached metadata differs.
Understand identity, launch and display as different concerns
The name member is a human-readable application name, and short_name is a shorter alternative where space is constrained. Neither is the application’s canonical identity. The manifest’s id member provides an identifier used in app identity processing, while start_url establishes a preferred launch URL and scope helps define the navigation boundary. They must not be translated as ordinary words. A readable path such as /study/ remains a technical address even if another language has a more natural term for study.
This separation matters when an installed app is updated. Suppose an editor translates id to match the Chinese label. A browser may perceive the manifest as describing a different application. The resulting user experience could involve duplicate icons or an update that does not associate with the existing installation. Even if a particular browser tolerates the change, the team has crossed a release-management boundary rather than performed a translation. Keep a canonical manifest-identity record and diff it against every localized variant.
The same principle applies to shortcut URLs. A shortcut named “Open today’s tasks” might point to /app/today. Translating the label should not send students to /app/archive or to a URL made by translating the English word “today.” Some sites implement localized routes intentionally, but changing the route requires engineering acceptance tests and an explicit routing policy. The translation task should preserve destinations by default. A good QA harness compares each shortcut’s label and target as separate fields rather than treating the whole shortcut object as translatable.
Interpret the October 2026 Working Draft carefully
The W3C Working Draft dated 26 October 2026 defines localizable members with corresponding *_localized maps. In its current model, app-level name, short_name and icons have localized counterparts; shortcut items may have localized name, short_name, description and icons. Language maps associate a language tag with a localized value. Some values can be strings, while other cases can carry additional direction or language metadata according to the draft’s definitions. Exact behavior must be checked against the draft version used by your project.
A draft feature is not a promise of broad deployment. The specification itself warns that it is unstable and that browser implementations may differ. Keep that warning visible in project documentation and procurement decisions. If a product must support many existing devices, do not rely solely on name_localized appearing in a manifest. Investigate whether a specific platform supports it, whether a separate manifest or installation experience is needed, and how the app behaves when no localized value is recognized. A tested fallback is part of the feature, not an embarrassing exception.
Distinguish normative claims from editorial preferences. The draft describes processing requirements and language selection behavior, but it cannot tell a team which translation best represents a particular school’s brand. A regional title might use a familiar name or a transliteration. That choice belongs to the institution and its audience. Store decisions in a style guide; then use the manifest mechanism to supply the approved words. Correct syntax without an agreed naming policy can produce inconsistent branding across installed icons, notifications and the site itself.
Build a small manifest fixture without changing routes
This illustrative JSON keeps identity and routing independent from display text. It supplies an English default and Simplified Chinese names through the draft localized fields. It also includes a shortcut whose URL remains the same in either language. The sample intentionally omits icon assets and full production metadata to keep the identity-versus-display distinction visible; it is a syntax fixture, not an installability or browser-compatibility certificate.
{
"id": "/planner/",
"start_url": "/planner/",
"scope": "/planner/",
"display": "standalone",
"lang": "en",
"name": "School Study Planner",
"short_name": "Planner",
"name_localized": {
"zh-Hans": "学校学习计划",
"en": "School Study Planner"
},
"short_name_localized": {
"zh-Hans": "学习计划",
"en": "Planner"
},
"shortcuts": [
{
"name": "Today's tasks",
"name_localized": {"zh-Hans": "今日任务"},
"url": "/planner/today"
}
]
}A JSON parser can confirm that the object is well formed. A manifest-processing implementation must still decide which fields it supports, resolve URLs according to its rules and apply its locale-selection behavior. In a useful test, record the selected language and then compare the actual installed icon label and shortcut menu with the expected text. A passing parser does not prove that name_localized was used; an older browser may ignore it and show the English default. That result is a compatibility fact requiring a product decision.
Build a baseline from the existing shipping manifest before editing. Store id, start_url, scope, display, icon references and every shortcut URL. After localization, compare the values byte for byte unless engineering has separately authorized a change. The localized fields should be additions or approved text substitutions, not a justification for changing access paths. Test the English default again after adding Chinese so that supporting a second audience does not accidentally reduce usability for the first.
Choose correct language tags and direction
A language map key describes the intended language or locale of the value. Use tags consistently with the organization’s localization policy, such as zh-Hans for Simplified Chinese. Do not put English text under a Chinese key merely because the intended user lives in a Chinese-speaking region. Nor should a translator guess a script from a geographic code. A human-facing application name can include proper names, borrowed words and mixed scripts; the tag still needs to describe the language strategy used for that label.
Text direction is an additional concern for right-to-left scripts. The Working Draft’s localized value model can carry direction information in supported forms. However, a team should test what the target browser actually renders and how the host operating system lays out icons and shortcuts. Translating Arabic words without direction review can produce awkward punctuation or misordered mixed-script names. The issue is not just cosmetic: a student might tap the wrong shortcut when similar items become visually hard to distinguish.
Language selection can differ from a website’s selected locale. The phone’s preferred languages, the browser’s settings and the app’s own profile can disagree. A team must decide what “correct language” means for installation metadata and identify which settings the user agent actually uses. A website toggle cannot be assumed to rewrite the installed name immediately. Explain this to stakeholders before testing so a mismatch is investigated as either a feature-support limit, a state problem or a product policy choice rather than blamed on the translator.
Write names that survive cramped home screens
A long application name may work in an installation dialog but become unreadable beneath a phone icon. Treat short_name as a genuine editorial field, not a blind truncation of the full name. A useful short name identifies the correct app among neighboring icons. If several school products share a generic label like “Study,” users may be unable to tell them apart. Test candidate wording on devices with different icon grids and font sizes. Screen-space constraints must be evaluated with real renders, not with a universal character limit guessed from English.
Brand consistency is especially important when names contain a school, organization or product trademark. Some names should stay in their original script, while surrounding descriptors may be translated. Create an approved naming convention that states which parts remain stable and what short forms are permitted. A translator might propose a linguistically elegant version that no longer matches the name parents see on the school’s information sheet. The technical manifest may accept it, but users would lose confidence because they cannot easily recognize the product they installed.
Avoid making the short label more specific than the full label in ways that change the promise. A planner that only tracks homework should not be translated into a phrase implying it manages grades, attendance and school transport. Evaluate names with actual users who know the app’s function. Ask what they would expect to happen when tapping the icon. Where the translation creates a broader expectation, revise it. Names are extremely short texts, but they carry a product claim and deserve careful semantic review.
Keep every shortcut's action clear and stable
A shortcut menu compresses a workflow into one touch. For a study planner, “Today,” “New assignment” and “Calendar” might represent different destinations. Translate each label as an action or destination appropriate to the platform’s conventions, and preserve its associated URL. Avoid using a vague noun when the underlying action is destructive or irreversible. The fact that the label appears in a small menu makes precision more important, not less; a user may not see explanatory context before tapping.
Where the draft supports localized descriptions on shortcut items, use them to distinguish similar actions without repeating the title mechanically. A description for “New assignment” might explain that it opens a blank entry form rather than a list of existing tasks. Do not translate that into a promise that a task is saved automatically. Every shortcut has a functional contract with the application route. A reviewer should activate each translated shortcut from the operating system menu and inspect the resulting screen, authentication state and ability to return to the home context.
Test shortcuts under realistic states. A signed-out user may be redirected to login, while a signed-in user reaches the requested view. An offline app may show cached content or a clear unavailable state. The translated name should not promise a fresh timetable when the app has no connection. These are context-dependent expectations: the route may be technically unchanged but the visible experience misleading. Capture state, expected result and actual result for each locale. If a shortcut cannot work offline, a clear fallback is better than an unexplained blank screen.
Localized icons are more than text swaps
The Working Draft describes localized icon resources as part of its localizable-member mechanism. A team may use different artwork when an icon contains language-specific text or culturally meaningful imagery. This is not permission to replace a recognizable brand icon casually. A localized icon may affect recognition, accessibility and trust. Review the design at several sizes, including cases where the browser selects a different icon purpose or resolution. Check that the icon corresponds to the same application identity and action as the default.
Some icons contain no text, making localization unnecessary. Creating variants anyway increases asset maintenance and the risk that one image will become outdated. If the app uses a book and pencil as a neutral symbol, translating a label may be enough. If the icon contains the word “Planner,” a translated version may help, provided contrast, legibility and design consistency survive the change. The choice should be driven by user comprehension and supported platform behavior, not by a requirement to change every field for every language.
Ensure asset paths remain correct and available over the same origin and deployment lifecycle as the manifest. A translated icon URL that returns a missing file can cause an inconsistent installation display even while localized text works. Test the network response, MIME type, image dimensions and platform rendering. Avoid embedding a translated word as a new image when accessible naming could be handled as text. If the project depends on icon localization, add explicit asset ownership and regression testing to the release checklist.
Plan for fallback without falsely claiming support
Every localized member should coexist with a meaningful default when the specification’s model calls for one. The default is not an inferior placeholder; it is what some devices or unmatched locales may display. Choose text that remains understandable to the widest appropriate audience and test it on browsers that do not support the draft’s language maps. A release that looks excellent only on one development browser is not a successful multilingual deployment if most students still receive broken or ambiguous installation labels.
Fallback also needs to be judged semantically. If a browser chooses English for a missing Tamil label, the app should not claim it has a complete Tamil installation experience. The in-app interface may be fully translated while the installed icon label is not. Communicate that limitation clearly in release notes or supported-device guidance, and prioritize missing language coverage based on user impact. Never populate a target-language key with unreviewed machine output solely to make a completeness spreadsheet show one hundred percent.
Test language preferences deliberately. Try a device whose first preference matches the target, another where it is the second preference, and another with an unsupported locale. Record which label appears and whether the result aligns with the browser’s documented processing. Where behavior is inconsistent, avoid asserting that the manifest is wrong without examining implementation status and cache state. A good QA report distinguishes translation defects from missing feature support, because the repair path and owner differ.
Understand installation updates and caching
Installable web apps can retain manifest-derived metadata beyond the page session in which a tester changed language. A developer who edits name_localized and reloads the site may still see an older home-screen label. That does not necessarily mean the JSON edit failed. The app’s installation lifecycle, browser refresh behavior and operating-system cache can all matter. A reliable test records whether the app was newly installed, upgraded, uninstalled or reinstalled, and avoids comparing two devices with different histories as though they were identical.
Do not respond to every stale label by changing id. That converts a synchronization problem into a potential identity problem. First confirm that the new manifest is served with the expected content, that its URL and cache policy are correct, and that the browser recognizes the localized member. Then use the product’s documented update process. If a platform cannot update a particular installation label promptly, document the limitation. An artificial identity change can create duplicate applications and confuse people who already saved tasks or preferences.
Regression testing should cover both existing and fresh installations. A new student installing the app today may get the correct translated name, while a student who installed it last month sees the previous name. Both are part of the audience. Record what is expected of updates, what is observed and any safe user guidance. Avoid promising that changing a language preference will immediately rename every existing icon unless that exact behavior has been verified on the target browser and operating-system versions.
Avoid changing route semantics while translating wording
A manifest’s start_url can contain query strings or paths that are meaningful to the application. It may look like a sentence fragment, but it is not an ordinary translation unit. If a product wants language-aware entry points, design that routing separately. For example, a stable start URL can read a saved preference and serve localized content. Another product may use deliberate locale routes. Both are engineering choices with authentication, deep-link and offline consequences. A translator should not invent a new URL simply by translating a path segment.
The scope member defines a navigation boundary that affects which URLs the app considers part of its experience. Changing it in a language file can alter which pages open as part of the installed app. A user might suddenly see an external browser window for a lesson that used to remain inside the app. The translated text might still be perfect. That is why scope is included in the frozen baseline and why a launch-path smoke test belongs in translation QA rather than in an unrelated future technical audit.
A shortcut URL should also retain its authorization and privacy expectations. A route that opens a private student dashboard must not become a public share page merely because one label was renamed. Test signed-in and signed-out states and avoid embedding sensitive tokens in translation assets or manifest query parameters. The manifest can be publicly fetched; it is not a place to store secrets. The localization team’s goal is to explain existing safe actions, not design new routes without appropriate security review.
Test the installed experience with users
A useful test session begins with an actual install, not an inspection of source code. Give a participant a device set to the target language, have them locate the app in the launcher, open it, use one shortcut and report whether it did what the label suggested. Observe confusion rather than explaining the design to them. If users cannot distinguish “Today” from “Upcoming,” the translations may need adjustment despite being dictionary-correct. The observed task is the ground truth of the interface’s meaning.
Repeat the test with a screen reader or platform accessibility feature where available. The installed app’s accessible name may be derived from metadata differently from the visible truncated label. Check that speech identifies the app and menu actions unambiguously. A shortcut whose visible text is adequate but spoken name is unexpectedly truncated can frustrate users who rely on auditory navigation. Record the exact device and accessibility settings so the result can be reproduced rather than treated as a vague localization impression.
Try language switching after installation, with expectations appropriate to the platform. The in-app content may change immediately, while installation metadata follows a different lifecycle. Explain that difference in a help article if it affects real users. A good product does not leave people guessing whether they installed the wrong app. Keep the acceptance tests separate: in-page localization, install metadata localization, launcher shortcut behavior and update behavior. All four matter, but one passing result does not prove the other three.
Diagnose a missing Chinese app name
Suppose the manifest contains a correct name_localized map, yet the installed icon remains English. Begin with a network inspection of the served manifest and confirm that the relevant localized field is present in the bytes the browser fetched. Then check the selected platform’s support for this Working Draft feature. If the browser ignores the member, the translation data may be sound while the platform simply lacks the capability. Do not “fix” that by rewriting name into Chinese if the default is needed for English users.
If the browser supports the member, inspect locale preference matching, JSON syntax, the baseline lang, the localized map’s key and the installation state. A mismatch such as a wrongly labeled script or an old cached manifest could explain the result. Create a fresh-install control test to separate cache behavior from language-selection behavior. Log actual values, not impressions. This disciplined sequence avoids wasting translator time on a problem owned by browser compatibility or deployment configuration.
A different report might say that the translated shortcut launches the wrong page. In that case, first compare the shortcut URL with the frozen baseline and trace what the application router does after activation. If the URL changed, restore the intended route through an authorized code fix. If the URL is unchanged but the app redirects unexpectedly for one locale, inspect locale-aware routing and authentication state. Rewriting a perfectly good shortcut label will not repair a route. Every symptom needs a diagnostic path appropriate to its cause.
Changed-context transfer exercise with answer
A community library turns its study planner into a family reading tracker. The English installed name becomes “Family Reading Log,” and new shortcuts open “Borrowed books” and “Reading goals.” The mobile app must support English, Malay and Simplified Chinese. Existing users have saved reading lists tied to their installation. The challenge is to explain which manifest elements can be localized and which changes belong to a product migration rather than translation. Also explain how you would test an old installation and a new installation.
The correct approach freezes the existing application identity unless the product owners deliberately decide on a separate app. The new name and its short form can receive reviewed language-map values where supported, with an understandable default. Each shortcut gains a localized display name while its destination is specified and tested by engineering. If the new features require new routes, those routes must be created and verified before localization. Changing id, scope or saved-data paths to match a translation would put existing reading lists at risk and is not part of the language task.
For testing, create a fresh installation in each supported language and inspect the launcher label, shortcuts, launch page and fallback. Separately upgrade an installation with existing lists and verify that its identity and saved data remain intact. Test a browser with no support for localized members and record the displayed default rather than claiming success. Ask families which shortcut they expect to open borrowed items. This exercise transfers the method from homework planning to reading records while preserving the crucial boundary between copy and product identity.
Practical release checklist
Before release, record the exact W3C Working Draft version and implementation support; preserve id, start_url, scope, icon references and shortcut URLs; maintain approved default names; tag every localized value appropriately; review text direction for right-to-left scripts; test short-name truncation; and verify the installed result on target browser and operating-system versions. Keep a table of each field, expected displayed text, actual displayed text, device, language preferences and installation state. Those details make a localization finding repeatable.
Separate blocking failures from support limitations. A shortcut pointing to the wrong action, an accidentally changed app identifier or a deceptive label is a release blocker. A browser that has not implemented a draft feature needs a documented fallback and a product decision, not a claim that translation is impossible. If localized icons are introduced, check image legibility, file availability and accessible names. If the team cannot test one platform, mark coverage unverified instead of inferring behavior from another platform’s success.
The release review should include a bilingual language reviewer, a developer who understands routing and installation identity, and someone responsible for the app’s product naming. For a school app, have a learner or parent perform one complete task without guidance. Save the test evidence and retest when the spec changes, the browser updates or the app changes its navigation. A good release is one that people can recognize and operate safely, not one that merely contains a new JSON property.
Separate desktop, mobile and browser installation paths
A team often tests its translated app name on a single Android handset and declares the manifest complete. That conclusion is too broad. An installation prompt, a launcher icon, a browser app list, an operating-system search result and a desktop shortcut can each derive display metadata through different timing and implementation paths. Write an observation sheet for every supported browser and operating-system combination: when the manifest was fetched, whether the install was new or existing, which preferred languages were configured, which exact text appeared, and what happened when the app was opened. Compare against the same build using the default locale. The engineering team can then tell a string-selection failure from an unsupported draft member, a stale installed record, or a browser-managed name chosen from an older manifest. Do not infer behavior from a screenshot without platform and build identification.
The default manifest values remain a product responsibility even after localized members are introduced. Imagine a school app used by parents who share a household computer with different language preferences. Replacing the base name with one target language may improve a single installation while damaging discoverability for everyone else on a platform that ignores name_localized. A robust launch plan chooses a truthful fallback, verifies a short and recognizable short_name, and does not rely on optional draft features as the sole path to basic usability. If product stakeholders need multilingual home-screen names now, check the supported mechanism in each target environment; where unavailable, explain the limitation and consider a deliberately chosen neutral name rather than fabricating browser support. A tested fallback is part of the translation, not an embarrassing exception to it.
Guard against metadata changes that appear only after an update
Installation metadata has a longer life than most interface copy. A parent may install the app during registration season and never reinstall, even after several web releases. A translation QA plan must therefore compare a clean installation with an update from a known previous version. Before testing, capture the original manifest identity, start URL, scope, icons and shortcut targets. After updating the localized fields, verify that the app still opens the same saved workspace and does not create an unexpected second installation. If the launcher name remains old, identify whether the platform refreshes metadata, whether a manual refresh is needed, or whether the product must accept a limitation. Do not “solve” the visible issue by changing the manifest id or its start_url without a separate migration decision. The cure can be more damaging than the defect because installation identity and routing outlive the translation project.
For shortcut names, test actual consequences rather than checking only words. A translated “Homework” shortcut must take a signed-in learner to the intended homework destination or an appropriate login handoff. If it opens an unrelated timetable because the route was accidentally localized, the string may be beautiful but the feature is broken. Capture the expected route, any query string that carries task identity, and the behavior when authentication is absent. Test long labels, mixed scripts, and devices that truncate names to different lengths. When the localized title is shorter than the source, confirm that it still distinguishes the action from other shortcuts. When it is longer, do not remove a safety-critical distinction simply to fit a visual limit; instead test a genuinely concise equivalent with native-language reviewers.
Document support without overstating a draft
A standards draft describes a proposed interoperable model, not proof that browsers already ship it. For the 26 October 2026 Web App Manifest Working Draft, treat localized members as specifications to investigate and test. Record the exact browser build, device, observed fallback and date of the check alongside each claimed capability. Avoid a marketing statement like “all home screens translate automatically” based only on the JSON containing several language keys. If a browser version supports only the base name, that is an implementation fact to convey. If a future specification revision changes matching or naming rules, rerun both parsing and installed-behavior tests. Translators and developers can prepare high-quality localized values now while keeping release promises within observed support. This distinction protects the credibility of the service and helps future maintainers understand why a previously approved language entry may not appear on a particular device.
Limits and summary
The Web Application Manifest specification was still a Working Draft on 26 October 2026, and its localized-member section may change. This article describes the draft’s model and a practical test approach; it does not promise that name_localized or localized icons work on every browser today. HTML page language, website translation systems and installed-app metadata are related but separate layers. Every deployment should check the current specification and actual implementation compatibility before making support claims.
An installed app name is a short text, but its technical environment is complex. It can be cached, interpreted by an operating system and presented alongside other apps. A translation that is linguistically elegant but shifts product identity, action semantics or a saved-data relationship is unacceptable. Conversely, a technically valid language map that no browser uses may not solve the user’s problem. The responsible workflow measures both correctness of data and actual behavior on the intended devices.
The durable rule is to localize what a person reads while preserving what an application is and where its controls lead. Keep stable identifiers and routes under engineering control, use reviewed language maps and defaults, and test installation and shortcut actions with real users. This method transfers to many multilingual software products because it puts meaning and identity in separate review lanes and refuses to confuse draft syntax with proven functionality.
Frequently asked questions
1. Is `name_localized` universally supported by browsers?
No such universal claim is justified. The 26 October 2026 W3C specification is a Working Draft and browser behavior varies. Feature-test your target platforms and maintain a usable default.
2. Can I translate the manifest `id`?
Not as a localization edit. It participates in application identity. A change can alter update or installation behavior and requires separate engineering review.
3. What differs between `name` and `short_name`?
The full name is intended for contexts with more space, while the short name supports constrained displays. Both require meaningful editorial review because a shortened translation can become ambiguous or misleading.
4. Should shortcut URLs change when their labels change language?
Normally no. Preserve the intended destination. Locale-specific routes can be engineered deliberately, but translating a path by intuition is unsafe.
5. Does switching a website's language rename an installed icon immediately?
Not necessarily. The installed metadata may be processed or cached through a separate lifecycle. Test the device and browser rather than assuming the page language controls the launcher.
6. How should right-to-left names be tested?
Review language and direction metadata, inspect mixed-script punctuation on real devices, and test both visible labels and spoken accessible names. Platform support still matters.
7. Are localized icons always necessary?
No. A language-neutral icon may already work well. Localize an icon when its text or imagery needs adaptation and the target platform supports the relevant mechanism.
8. What should happen for an unsupported language?
A documented fallback should provide a meaningful default. Do not fill target language keys with unreviewed text to create a false appearance of full support.
9. Why do fresh and existing installations show different labels?
Installation metadata can be cached or updated according to platform-specific behavior. Compare served manifest data, update state and supported features before changing identity fields.
10. What proves that app identity survived translation?
Compare id, start_url, scope and shortcut destinations to a frozen baseline, then test launches and upgrades with existing saved data. A correct translated label alone does not prove identity stability.
Authoritative sources
- W3C Web Application Manifest, Working Draft 26 October 2026
- W3C Web Application Manifest, current published version
- W3C Web Application Manifest editor’s draft
- MDN Web App Manifest documentation