Download sample spreadsheets to see the structure for importing translation data:

Altera supports both importing and exporting translations. The export format is compatible with Shopify's native translation import in the admin, and we've added extra columns to make it easier to identify what's being translated.

Translation spreadsheets have one row per translatable field per locale. Each row shows:

You can export translations from one store and import them into a different store. Altera uses the Handle column to match resources across stores, since Shopify IDs differ between stores. During import, Altera first checks whether the resource ID exists on the target store. If it doesn't, it falls back to looking up the resource by handle. This works for products, collections, pages, blogs, articles, menus, metaobjects, metafields, product options, product option values, and product variants.

The translation file format is compatible with Shopify's native translation import functionality in the admin. You can export translations from Altera, edit them in your spreadsheet software, and import them back into Altera or import them directly into Shopify.

To make translations easier to work with, we've added several helper columns that aren't part of Shopify's standard format:

These additional columns make it much easier to identify what you're translating, especially when working with nested resources like product options or metafields. For example, when translating a metafield, you can see the namespace and key in the Handle column and the parent resource's handle in the Parent Handle column.

Note: The Type and Identification columns are part of Shopify's standard translation format and are required for importing translations back into Shopify. When importing into Altera, at least one of ID, Identification, or Handle is required.

The following resource types can be translated:

The type of Shopify resource being translated. See Translatable Resource Types for a complete list of supported types.

This column is part of Shopify's standard translation format.

Controls how the translation row is processed during import.

If omitted, defaults to MERGE.

Each row can have its own Command value. For example, you can MERGE most rows in a group while using DELETE on specific rows to remove individual translations.

The full Shopify Global ID (GID) for the resource. This includes the resource type and numeric ID in a URI format.

This is an Altera-specific field that provides the complete resource identifier.

The numeric ID portion of the resource's Shopify Global ID (GID). This is extracted from the full GID format (e.g., gid://shopify/Product/8079393226938).

Leading single quotes (e.g., '8079393226938) are automatically stripped during import, since some spreadsheet applications prepend these to preserve numeric formatting.

This column is part of Shopify's standard translation format and is required for importing translations back into Shopify.

The URL-friendly handle for the resource. During import, the Handle column is used to identify resources when IDs don't match the target store, which is how cross-store translation transfers work. Not all resource types have handles.

The handle format varies by resource type:

For nested resources (like product options or metafields), this shows the type of the parent resource. For top-level resources, this will match the Type field. For metafields attached to a variant, this will be PRODUCT_VARIANT.

This is an Altera-specific field that provides additional context about the resource hierarchy.

For nested resources, this shows the full GID of the parent resource. For top-level resources, this will match the ID field.

This is an Altera-specific field that provides additional context about the resource hierarchy.

For nested resources, this shows the handle of the parent resource. This is an Altera-specific field that makes it easier to understand the context of what you're translating.

The parent handle format varies by parent type:

The specific field being translated. Common field keys include:

The available fields vary by resource type. For example, products have fields like title and body_html, while metafields have a single value field.

The language code for the translation. This uses ISO 639-1 two-letter language codes, optionally followed by a region code (e.g., en, fr, es, pt-BR, zh-CN).

The available locales are determined by which languages you've enabled in your Shopify admin under Settings > Languages.

The name of the market this translation is scoped to. When empty, the translation is global and applies to all markets (the default behavior).

Market-scoped translations let you override global translations for specific markets. For example, you could have a global French translation and a different French translation specifically for the Canada market. You can also use market-scoped translations to override content in the store's primary language for a specific market.

On export, this column contains the market name. On import, you can use the market name (case-insensitive), a numeric market ID, or a full GID (e.g., gid://shopify/Market/12345).

This column is only populated during export when you add a Market filter. Without a market filter, only global translations are exported and the Market column will be empty.

The original content in your store's primary language. This is the content that should be translated into the target locale.

For fields like product descriptions, this contains the HTML content. For plain text fields, it contains the plain text.

The translated content for the target locale. If no translation exists yet, this field will be empty.

For rich text fields, this should contain the translated HTML. For plain text fields, it should contain the translated plain text.

You can use these filters to limit which translations are exported:

Resource-level filters only apply to their respective resource types and nested metafields. Other resource types will pass through unfiltered. For example, product filters only affect PRODUCT, PRODUCT_OPTION, and PRODUCT_OPTION_VALUE resources; collection filters only affect COLLECTION resources and their metafields; and metaobject type filters only affect METAOBJECT resources and their metafields.

When exporting product translations, you can filter by product attributes:

When exporting collection translations, you can filter by collection attributes:

When exporting metaobject translations, you can filter by metaobject type:

When exporting theme translations (ONLINE_STORE_THEME), you can filter by theme ID. This is useful when you have multiple themes and only want translations for a specific one.

Theme filters apply to all theme-related translation resources, including nested resources like JSON templates, section groups, and locale content.

You can filter translations by market to export only market-scoped translations for specific markets.

When a market filter is set, the export contains only market-scoped translations for the matching market. Global translations are not included. Without a market filter, only global translations are exported.

When a market filter is active, the store's primary language is included in the export alongside all other languages. This is because Shopify allows market-scoped translations to override content in the primary language for a specific market.

If no language filter is set alongside the market filter, Altera only exports languages that are enabled for that market (based on the market's web presence configuration in Shopify). If a market has no web presence configured, all published languages are exported. You can override this by adding an explicit language filter.

You can filter translations by the field key to limit which translatable fields are exported. This is useful when you only need specific fields (like title) or want to exclude certain fields (like checkout translations).

The field filter applies across all resource types. Common field keys include title, body_html, meta_title, meta_description, name, and value. Theme translations use dot-separated keys like shopify.checkout.taxes.vat_number.status.invalid_number.ee.

Export all product translations for French and Spanish:

When working with nested resources like product options and option values, the parent columns help you understand the context:

The Handle column uses a 1-based index to identify which option it belongs to. 1 refers to the first option on the product, 2 to the second, and so on. For option values, the format is [index].[value_name] (e.g., 1.Small means the value "Small" under the first option).

For metafield translations, the Handle column shows the metafield namespace and key:

This shows you're translating the custom.care_instructions metafield for the "cotton-tee" product.

Metafields attached to product variants use PRODUCT_VARIANT as the Parent Type. The Parent Handle uses the product_handle.variant_title format so the correct variant can be identified across stores:

This format matches the variant reference convention used elsewhere in Altera. If the variant title contains commas, they are escaped as \, in the handle.

For metaobject translations, the Handle column uses the [type].[entry] format:

The handle color.red means this is the "red" entry of the "color" metaobject type.

The meta_title and meta_description fields only appear in translation exports when the resource has custom SEO values explicitly set. If a product (or collection, page, etc.) does not have a custom meta title or meta description, Shopify defaults to using the resource's title and the beginning of its description. In this case, Shopify does not create a separate translatable entry for those fields in the API.

To make SEO fields available for translation:

Once custom SEO values are set, the fields will appear in Shopify's Translate & Adapt app and in Altera's translation export. If you don't set custom values, Shopify will automatically use the translated title and description as the translated SEO fields, so custom SEO translations are only needed when you want the SEO text to differ from the resource title and description.

Translation exports and imports can be slower than other data types because of how Shopify's translation API works. To provide useful context in the export (like handles and parent handles), Altera needs to make additional API calls to look up each resource. This extra step helps you identify what you're translating but adds processing time, especially for large stores.

Additionally, Shopify's translation APIs have limited filtering options. While we apply as much filtering as possible server-side, some filters (like product status or tags) need to be applied within the Altera app after retrieving the data. This means more data may be fetched than what ends up in your final export.

If you're experiencing extremely slow translation imports or exports, please contact us and we'll look into whether there's a way to speed things up for your specific case.

If you have suggestions or feature requests, please contact us