On this page
Why older localization advice is now stale
Large multilingual extensions previously failed deployment when the combined contents of their locales folder exceeded 256 KB. Teams sometimes removed languages, shortened copy, or built custom translation loading to work around the ceiling. Shopify’s October 30 change removes that combined limit for UI extensions across API versions. It does not change locale naming, fallback behavior, or the individual-file size limit.
What to change in a real app
Audit any workaround that exists solely because of the old aggregate limit. Restore supported locale files in the extension’s locales directory, using Shopify’s normal naming convention such as de.json and pt-BR.json. Keep each JSON file below 30 KB and retain the required fallback/default translations.
extensions/
my-extension/
locales/
en.default.json
de.json
fr.json
pt-BR.json
Do not assume a larger translation bundle means all strings will appear automatically. Translation keys must match those used by the extension, JSON must parse, and locale fallback must be tested with real store or buyer language settings. An extension may also have unrelated compiled bundle limits; this change specifically concerns the combined locale-file size.
Deploy and verify
Run shopify app deploy to create a new app version. Shopify says existing extension versions keep working and no action is required if you never reached the previous limit. Releasing additional languages is optional, but the deployment and preview are still your responsibility.
How to test this
- Inventory locale files and confirm each individual JSON file is below 30 KB.
- Validate JSON syntax and verify keys against the default locale.
- Add back a previously excluded locale, then run
shopify app deployin a development app. - Set the test store or customer locale to the newly restored language and verify translated strings.
- Switch to an unsupported locale and confirm the expected fallback text appears.

