Sample Files

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

Product Translation Example - Shows how to import translations for products
Metaobject Definition, Entry and Translation Example - Shows how to import metaobject definitions, entries, and their translations together

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.

Overview

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

The resource being translated (type, ID, handle)
The parent resource (for nested items like product options or metafields)
The specific field being translated
The default content (in your store's primary language)
The translated content (in the target locale)

Cross-Store Transfers

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, and product option values.

Shopify Compatibility

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.

Additional Columns for Context

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

ID: The full Shopify Global ID (GID) of the resource (e.g., gid://shopify/Product/8079393226938)
Handle: The handle of the resource being translated (e.g., premium-cotton-tee)
Parent Type: The type of the parent resource (for nested items)
Parent ID: The full GID of the parent resource
Parent Handle: The handle of the parent resource

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.

Translatable Resource Types

The following resource types can be translated:

ARTICLE: Blog articles
BLOG: Blog information
COLLECTION: Product collections
DELIVERY_METHOD_DEFINITION: Shipping methods
EMAIL_TEMPLATE: Transactional email templates
FILTER: Collection filters
LINK: Navigation menu links
MEDIA_IMAGE: Media file alt text
MENU: Navigation menus
METAFIELD: Custom metafields
METAOBJECT: Metaobject content
ONLINE_STORE_THEME: Theme customizations
PAGE: Store pages
PAYMENT_GATEWAY: Payment method names
PRODUCT: Product details
PRODUCT_OPTION: Product option names (Size, Color, etc.)
PRODUCT_OPTION_VALUE: Product option values (Small, Blue, etc.)
SELLING_PLAN: Subscription plan details
SELLING_PLAN_GROUP: Subscription plan groups
SHOP: Store information
SHOP_POLICY: Store policies

Fields

Type

Description	Example Value
Resource type	`PRODUCT`

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.

Command

Description	Example Value
Import command	`MERGE`

Controls how the translation row is processed during import. See Import Commands for details.

If omitted, defaults to MERGE. Note that the UPDATE, REPLACE, and MERGE commands will function the same. NEW will skip rows if a translation already exists.

ID

Description	Example Value
Shopify Global ID (GID)	`gid://shopify/Product/8079393226938`

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.

Identification

Description	Example Value
Shopify resource numeric ID	`8079393226938`

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).

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

Handle

Description	Example Value
Resource handle	`premium-cotton-tee`

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:

PRODUCT, COLLECTION, PAGE, BLOG, ARTICLE: The URL-friendly slug (e.g., premium-cotton-tee)
METAFIELD: The namespace and key separated by a dot (e.g., custom.care_instructions)
METAOBJECT: The metaobject type and entry handle separated by a dot (e.g., color.red)
PRODUCT_OPTION: A 1-based index representing the option's position on the product (e.g., 1 for the first option, 2 for the second)
PRODUCT_OPTION_VALUE: The option's 1-based index and the value name separated by a dot (e.g., 1.Small, 2.Blue)

Parent Type

Description	Example Value
Parent resource type	`PRODUCT`

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.

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

Parent ID

Description	Example Value
Parent resource GID	`gid://shopify/Product/8079393226938`

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.

Parent Handle

Description	Example Value
Parent resource handle	`premium-cotton-tee`

For nested resources, this shows the handle of the parent resource. For example, when translating a product option, this shows the product's handle.

This is an Altera-specific field that makes it easier to understand the context of what you're translating.

Field

Description	Example Value
Translatable field key	`title`

The specific field being translated. Common field keys include:

title: Resource title or name
body_html: HTML description or content
meta_title: SEO title
meta_description: SEO description
option1.name: Product option name (Size, Color, etc.)
alt_text: Image alt text

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

Locale

Description	Example Value
Target language locale	`fr`

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.

Default content

Description	Example Value
Original content in primary language	`Premium Cotton T-Shirt`

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.

Translated content

Description	Example Value
Translated content in target locale	`T-Shirt en Coton Premium`

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.

Export Filters

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

locale: Filter by language code (e.g., fr, es, de)
Supports comma-separated values: locale=fr,es,de
Use NOT_EQUALS to exclude specific locales: locale NOT EQUALS en
By default, exports all non-primary locales
type: Filter by resource type (e.g., PRODUCT, COLLECTION, PAGE)
Supports comma-separated values: type=PRODUCT,COLLECTION
See Translatable Resource Types for valid values
By default, exports all translatable resource types

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.

Product-Level Filters

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

product_id: Filter by product ID
Supports comma-separated values: product_id=123,456,789 to only export translations for those specific products
Can be combined with other product filters - when both product ID and other product filters are used, only products matching both conditions are included
product_status: Filter by product status
Options: active, draft, archived, unlisted
Example: product_status=active to only export translations for active products
product_tag: Filter by product tag
Example: product_tag=summer to only export translations for products tagged "summer"
Supports partial matching
product_created_at: Filter by product creation date
Example: product_created_at=2024-01-01 to export translations for products created on that date
Supports date ranges with GREATER_THAN and LESS_THAN relations

Collection-Level Filters

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

collection_id: Filter by collection ID
Supports comma-separated values: collection_id=123,456,789 to only export translations for those specific collections
Can be combined with other collection filters - when both collection ID and other collection filters are used, only collections matching both conditions are included
collection_handle: Filter by collection handle
Example: collection_handle=summer-sale to only export translations for that collection
collection_type: Filter by collection type
Options: custom (Manual), smart (Smart)
Example: collection_type=smart to only export translations for smart collections

Metaobject Type Filter

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

metaobject_type: Filter by metaobject definition type
Example: metaobject_type=color to only export translations for the "color" metaobject type
Supports comma-separated values: metaobject_type=color,material
Use NOT_EQUALS to exclude specific types
Use CONTAINS or NOT_CONTAINS for partial matching

Example Use Cases

Exporting Product Translations

Export all product translations for French and Spanish:

Select the Translations object type
Add filters: locale=fr,es and type=PRODUCT
Export the file

Identifying Nested Resources

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

Type	ID	Identification	Handle	Parent Type	Parent ID	Parent Handle	Field	Locale	Default content	Translated content
PRODUCT_OPTION	gid://shopify/ProductOption/123	123	1	PRODUCT	gid://shopify/Product/456	cotton-tee	name	fr	Size	Taille
PRODUCT_OPTION_VALUE	gid://shopify/ProductOptionValue/789	789	1.Small	PRODUCT	gid://shopify/Product/456	cotton-tee	name	fr	Small	Petit

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).

Working with Metafields

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

Type	ID	Identification	Handle	Parent Type	Parent ID	Parent Handle	Field	Locale	Default content	Translated content
METAFIELD	gid://shopify/Metafield/789	789	custom.care_instructions	PRODUCT	gid://shopify/Product/456	cotton-tee	value	fr	Machine wash cold	Laver à froid

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

Working with Metaobjects

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

Type	ID	Identification	Handle	Parent Type	Parent ID	Parent Handle	Field	Locale	Default content	Translated content
METAOBJECT	gid://shopify/Metaobject/1234	1234	color.red	METAOBJECT	gid://shopify/Metaobject/1234	color.red	display_name	fr	Red	Rouge

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

Limitations

No filtering by field: You cannot yet filter to export only specific fields (e.g., only titles, not descriptions)
Limited resource-level filters: Resource-level filtering is available for products, collections, and metaobjects. Other resource types (pages, blogs, articles, etc.) cannot yet be filtered by their attributes.

If you have suggestions or feature requests, please contact us

Metafield Definition Fields

Metaobject Fields

Metaobject Definition Fields

Metafields

How to Import and Export Shopify Translations

Translation Fields