Learn how to transfer localization files between Piano apps by downloading and uploading .PO files, including key considerations for merging translations and avoiding overwrites.
Downloading from the source app
-
Log into the Piano Dashboard for the source app.
-
Navigate to Manage→ Localization.
-
Open the "..." (ellipsis) menu at the right of each language.\n
-
Select Download to get the
.POfile for each language you want to transfer.
Uploading to the destination app
-
Log into the Piano Dashboard for the destination app.
-
Navigate to Manage→ Localization.
-
Open the "..." menu for the language you want to update.
-
Select Upload and upload the
.POfile.
Important considerations
-
The import tool will merge results — if the destination app already has a translation and the imported file doesn't include it, the existing translation in the destination app will be kept.
-
Context (
msgctxt) is required — Make sure your PO file entries include the proper context values. If entries are missing context, they may not be recognized during upload. It's recommended to first download the current translation from the destination app and then edit it, preserving the existing context. -
Entries with blank
msgstrvalues may be skipped during upload unless you explicitly choose to overwrite. -
Protected/system-level contexts (e.g.,
checkout.platform) cannot be edited via the Dashboard upload and will be ignored.
How do I avoid overwriting existing translations?
-
Download
.POfiles from both apps. -
Compare them using a text comparison tool.
-
Remove any keys from the source file that already exist in the destination file.
-
Upload only the file with the new keys to the destination app.
-
Verify that the upload summary shows only new keys being added, with no existing keys being updated.
For a complete overview of localization features and configuration, see Localization.