How to Import WooCommerce Categories with WPML from CSV

A translated category import is not just a list of names. It is a tree, and every branch also belongs to a WPML translation group. If the file identifies categories only by their visible label, a rename or repeated name can make the hierarchy ambiguous.

Shirely Category Matrix uses stable source identifiers for the tree and language-suffixed columns for the translated term values. That makes both relationships visible before the import.

Use source keys, not database IDs

A small two-language category file can look like this:

source_id,parent_source_id,name|en,name|de,slug|en,slug|de
tools,,Tools,Werkzeuge,tools,werkzeuge
drills,tools,Drills,Bohrmaschinen,drills,bohrmaschinen
cordless-drills,drills,Cordless drills,Akku-Bohrmaschinen,cordless-drills,akku-bohrmaschinen

source_id is the maintained identity of the category row. parent_source_id points to the parent's source key. The names and slugs can differ by language without changing the structural relationship.

Do not substitute numeric WordPress term IDs from another store. Those numbers are local to the source database. A category called “Accessories” is not a reliable key either: the same label can exist below two different parents, and translated names can change.

Plan the tree before the translation

Start with the source IDs and parent references. Check them as a plain hierarchy:

every child refers to an existing source ID;
a category never refers to itself;
there are no cycles;
top-level categories have no parent source ID;
source IDs are unique and remain stable between runs.

Then review the language columns. Use the exact WPML language codes active on the destination. Empty translations should be intentional and documented rather than the result of a failed join between language files.

The default language comes from WPML. Do not infer it from the first language column or hard-code a different policy into the source file.

Import the Category Matrix

Upload the UTF-8 CSV, choose the product-category taxonomy and Matrix Mode, then review the proposed mapping. Map the identity and parent columns explicitly if their headers were not recognized.

Select the Import Mode that matches the task. A new tree and a correction to an existing tree have different permissions. Preview a small branch before processing the complete taxonomy.

Shirely creates or updates the language terms, connects their WPML relationships and performs the closing hierarchy synchronization after the imported rows are in place. This closing pass matters because a child can appear before its parent in a real file. A temporary “saved as root” message can be informational; the final tree is what must be checked.

Test one complete branch

A useful sample contains more than two top-level categories. Include:

one root;
a child;
a grandchild;
translated names and slugs;
a category that already exists on the destination;
a deliberately missing translation if the production source contains one.

After import, inspect WPML's taxonomy translation view and the WooCommerce category screen. Then open the category archives on the storefront in every language.

Check:

parent–child nesting;
translated slugs and names;
language assignments;
translation-group relationships;
product counts and assignments where relevant;
breadcrumbs and navigation that depend on the hierarchy.

If WPML reports pending hierarchy changes, run its hierarchy synchronization and check the affected terms again.

Import products after the taxonomy is understood

When moving a new catalog, establish and verify the category tree before a large product import depends on it. Product rows may contain readable category paths, but the taxonomy Matrix is where portable source identity and translated hierarchy are explicit.

Keep the source keys unchanged between category and product workflows. If a category is renamed, update its translated name or slug while preserving source_id.

The multilingual product import guide covers the product side of this sequence.

Repeat imports process category rows

Category and Matrix rows are processed during every re-import. Repeatability depends on stable source keys, the selected mode and a source that includes only the fields you intend to maintain.

Shirely 1.3.0 catalog provenance helps prevent IDs exported from another store from being blindly treated as local. It does not remove the need to preview a cross-store category import or test the resulting tree.

Automation after a manual proof

A supported Category Matrix import can be saved as an Automation slot in Shirely 1.3.0. Use Run now for the first complete test and confirm the result in Run History.

WP-Cron provides hourly, twicedaily and daily schedules, but it is traffic-dependent and does not guarantee an exact time. Use system cron with WP-CLI when the timing must be predictable.

Do not overlap jobs that may change the same taxonomy or WPML/WCML translation groups. Same-slot locking is not global serialization for every import.

Measured scale, with context

One documented run processed 1,068 categories across four languages—4,272 rows—in 9 minutes 21 seconds. It was a measurement from a specific environment, not a promise for every hosting plan or taxonomy.

Hierarchy depth, hooks from other plugins, database state and the number of languages can all change the work performed. Use the measurement as evidence that the workflow has been exercised, then size the batch for your own staging environment.

FAQ

Can I use category names as the relationship key?

Avoid it. Names are translated, editable and not necessarily unique. Use source_id and parent_source_id for the portable hierarchy.

Must every parent row come first?

Parent-first is easiest to review. Shirely can defer hierarchy handling and run a closing pass, but the source still needs valid parent references and the final tree still needs QA.

Are tags imported the same way?

Tags and other non-hierarchical taxonomies do not have a parent tree. They can use Matrix language columns, but their verification focuses on language relationships and product assignment rather than nesting.

Treat the tree as data

Once category identity and parent relationships are explicit, translation becomes much less fragile. Build the source keys first, keep them stable, import a representative branch and verify real archives in every language before scaling up.

Read how Shirely handles category hierarchy for the internal model, or use the documentation for import settings and troubleshooting.