5 min read
Categories Guides

How to Import WooCommerce Products with WPML Translations

A multilingual product import has two jobs. WooCommerce needs correct products, prices, stock and attributes. WPML needs each language version connected to the right translation group. A file can look perfectly tidy and still fail the second job if identity is unclear.

Shirely's Matrix Mode keeps the related language values on the same source row. Shared product data appears once; translated copy uses a language suffix. That makes the relationships visible before the import begins.

Build one row around a stable product

A simple Matrix source can start like this:

sku,name|en,name|de,description|en,description|de,regular_price,stock
DRILL-100,Cordless drill,Akku-Bohrmaschine,18V workshop drill,18-V-Akku-Bohrmaschine,149.99,16

sku, price and stock are operational fields, so they remain unsuffixed. The product name and description are translated, so they use |en and |de.

Use the exact WPML language codes configured on the site. A column for a language that is not active cannot create a reliable language relationship merely because its suffix looks plausible.

For a cross-store import, SKU is the recommended ordinary product key. In multilingual Matrix Mode, Matrix ID / External ID can be used when SKU is not the right business key. A WordPress Product ID and a WPML TRID belong to the database that created them; do not assume those numbers are portable.

Separate shared fields from translated fields

Translated columns usually include product title, descriptions and slug. Shared fields often include SKU, price, stock, weight and dimensions. Shirely's Sync Core Data option controls copying the relevant non-translatable product data from the default-language product to its translations.

Be deliberate with taxonomies. Product categories and tags have language relationships of their own. If you are moving a new catalog, import and verify the translated taxonomy structure before relying on it in the full product run.

Global attributes have two supported paths in 1.3.0:

  • use a plain pa_color column for an attribute that is shared across languages;
  • use pa_color|en, pa_color|de and other language columns only with Translate global attributes (WCML Matrix opt-in).

The opt-in applies only to Product Matrix imports, requires the supported WPML/WCML stack, and expects the attribute taxonomy to be configured as translatable already. Shirely does not change that policy in WCML. Review its preflight warning and verify the terms on the storefront.

Variable products keep parent and variation rows

Matrix Mode does not flatten a complete variable product into one row. Use a Matrix row for the parent and one for each variation:

type,sku,parent_sku,name|en,name|de,regular_price,stock,pa_size
variable,TEE-400,,Everyday T-shirt,Alltags-T-Shirt,,,Small|Medium
variation,TEE-400-S,TEE-400,,,29.00,8,Small
variation,TEE-400-M,TEE-400,,,29.00,13,Medium

Put the parent first. Give every variation a unique SKU and point it to the parent with parent_sku. If translated global attributes are enabled, the language-suffixed attribute values also need to resolve correctly for each variation.

The variable-products documentation covers that structure in more detail.

Review mapping and Import Mode

Upload the CSV, confirm Matrix Mode and inspect every proposed mapping. Common headers may map automatically, but similar names are not always the same field.

Choose one of the exact modes:

  • Create & Update;
  • Only Create (skip existing);
  • Only Update (skip new).

A migration into an empty staging store may use a create path. A reviewed translation correction for existing products may use Only Update (skip new). The safe choice depends on what the source is allowed to do.

Shirely 1.3.0 catalog provenance prevents an exported foreign ID from being blindly treated as a local one. Natural keys, current destination data and the preview still decide whether the match is appropriate.

Test the awkward product, not the easy one

Create a small sample with:

  • a simple product with complete translations;
  • a product intentionally missing one translation;
  • a variable parent and two variations;
  • a translated category;
  • a shared attribute;
  • a translated global attribute if the WCML opt-in is in scope;
  • an image and a Global Unique ID if those fields are part of the project.

After import, use the language switcher and open each product on the front end. Check titles, URLs, categories, selectors, price, stock and images. Confirm the default language came from WPML and that translations belong to the same product family.

Do not treat a successful row count as proof that the translated storefront is correct.

Repeat and schedule with clear boundaries

Product and Matrix rows are processed on re-import. Smart Sync's unchanged-row skip applies only to posts, pages and custom post types with a mapped Record ID. Stable keys, a narrow field set and the selected mode make product re-imports predictable.

Shirely 1.3.0 can save a supported Matrix import as an Automation slot. Use Run now first and check Run History. Later, choose hourly, twicedaily, daily or WP-CLI through system cron.

WP-Cron depends on traffic and does not guarantee an exact start time. Schedule imports that can modify the same products, terms or WPML/WCML translation groups sequentially. Same-slot locking is not a global lock across every import path.

Headless runs exclude delete_non_matching, so an incomplete scheduled source cannot silently request a broad deletion.

FAQ

Do I need WPML for a normal product import?

No. WPML is optional for Shirely's standard imports. It is required for the multilingual relationships created by Matrix Mode.

Should translated fields use separate rows?

In Matrix Mode they use language-suffixed columns on the same row. Variable parents and variations remain separate rows because that is a WooCommerce relationship, not a language split.

Will a re-import always avoid duplicates?

No unconditional guarantee is responsible. The source needs a stable key, the correct Import Mode and a destination state that matches the chosen strategy. Preview and test.

Make the language relationship inspectable

The benefit of a Matrix file is not merely fewer CSVs. It lets you see the shared identity and every translated value together. Prepare that source carefully, prove the difficult rows on staging, and verify the actual storefront in each language.

Continue with the Matrix format guide or the dedicated category Matrix workflow.