Shirely

01 Installation

Getting Shirely running takes less than a minute.

System Requirements

01A Supported data types

Shirely 1.3.0 imports and exports WooCommerce catalog data, WordPress content and selected store data from CSV or Google Sheets. WPML is optional: Matrix Mode adds multilingual workflows, while single-language imports and exports work without WPML. Automation can save supported import and export jobs for on-demand or scheduled runs.

02 Dashboard Overview

The Dashboard provides quick access to the primary workflows and an overview of the server checks used by Shirely.

The dashboard contains three main areas:

• Welcome banner — One-click buttons for Start Import and Start Export.
• Quick Actions — Shortcuts to Import CSV File, Export All Posts, and Configure Settings.
• System Requirements — A live table checking PHP memory, WordPress memory, upload limits, max_input_vars, execution time, the upload directory, WPML status and the plugin database table.

03 Importing Data

The import wizard guides you through five steps: upload your file, map columns to WordPress fields, preview the changes, run the import, and review the results.

Step 1 — Upload File

Navigate to Shirely → Import. You will see the upload screen with a large drag-and-drop zone.

• Drag & drop your CSV file onto the zone, or click Browse Files to choose a file from your computer.
• Supported format: CSV (UTF-8 recommended). Maximum file size: 50 MB.
• Both comma (,) and semicolon (;) delimiters are auto-detected.
• Below the upload zone, a Previously Uploaded Files panel shows files from earlier sessions. Click Use File to reuse one without re-uploading.

Once the file is uploaded successfully, click Continue to Mapping →.

Step 2 — Map Fields

This is where you connect your CSV columns to WordPress/WooCommerce fields.

Import As

Select the content type from the dropdown. Post types come first — Products, Posts, Pages and any custom post type, plus Orders, Customers, Coupons and Reviews when WooCommerce is active — followed by a separator and the taxonomies, including Categories (product_cat), tags, and WooCommerce attribute taxonomies (pa_*).

Product Import Strategy

For product imports, the mapping screen provides these matching and existing-item options:

Field Mapping Table

Each row shows Source Column → WordPress Field → Sample Value. The Auto-Mapper automatically detects common column names like sku, title, regular_price, description, and stock_quantity.

WPML Language

When WPML is active, Shirely detects Matrix Mode automatically from language-suffixed headers such as title|en and title|pl. The mapping screen shows a Matrix Mode badge when this format is detected; there is no manual Matrix Mode toggle.

Step 3 — Preview

Before committing any changes, the preview screen breaks down what the import is expected to do. Five color-coded stats cards:

• Total Rows — number of data rows in your CSV
• Will Create (green) — new items to be created
• Will Update (blue) — existing items that will be modified
• Will Skip (gray) — unchanged records that will be skipped
• Errors (red) — rows with validation problems

Smart Sync Detection

Applies to posts, pages and custom post types imported with a mapped Record ID: records unchanged since the previous import are skipped automatically. Products, categories and Matrix Mode rows are always processed.

Confirmation Checkboxes

Before clicking Start Import you must confirm:

• “I have a recent backup of my database”
• “I understand that import may overwrite existing data”
• “I take full responsibility for the result”

Step 4 — Run Import

After clicking Start Import, the plugin processes your data in batches.

• A progress bar shows the current percentage.
• Real-time counters update as items are created, updated, skipped, or error.
• Processing happens in batches (default: 20 rows per request).
• Click Cancel at any time to stop further batches.

If the import stalls or the progress bar stops moving, try reducing the Batch Size in Settings. The most common cause is a PHP timeout.

Step 5 — Summary

When the import completes, the summary screen shows:

• View [Items] — links to your imported content
• New Import — start a fresh import session
• Detailed stats — Status, Total Rows, Created, Updated, Skipped, Errors, Duration, Average Speed
• Copy Debug Info — copies diagnostic summary to clipboard

04 Matrix Mode (WPML)

What is Matrix Mode?

Matrix Mode lets you manage all language translations from a single CSV row. Instead of importing separate rows for each language, you add language-suffixed columns.

Traditional approach (3 languages × 100 products = 300 rows):

sku,name,price,language
SHIRT-001,Niebieska Koszula,29.99,pl
SHIRT-001,Blue Shirt,29.99,en
SHIRT-001,Blaues Hemd,29.99,de

Matrix Mode approach (100 products = 100 rows):

sku,name|pl,name|en,name|de,price
SHIRT-001,Niebieska Koszula,Blue Shirt,Blaues Hemd,29.99

One row creates or updates the product in all WPML languages simultaneously, with automatic TRID translation linking.

Category Sync

Matrix Mode imports all categories in every language from a single CSV and automatically synchronizes the hierarchy. Parent-child relationships, slugs, and WPML translation links (TRIDs) are all created in one pass.

slug,name|pl,name|en,name|de,parent_slug
narzedzia,Narzędzia,Tools,Werkzeuge,
wiertarki,Wiertarki,Drills,Bohrmaschinen,narzedzia
szlifierki,Szlifierki,Grinders,Schleifer,narzedzia

Why this matters: Most importers require you to import categories language-by-language, then manually link translations. Matrix Mode does it in one import.

Automatic WPML Hierarchy Synchronisation

When the import completes, Shirely calls WPML’s hierarchy synchronization once, after the full imported category tree is in place. This is the closing pass that mirrors parent-child relationships across the imported language versions.

• Automatic, post-import — triggered once on completion, not per-row (which would be unreliable mid-import when parent terms may not yet exist)
• Full tree coverage — the entire imported hierarchy is synced in a single pass
• One closing pass — hierarchy synchronization runs after all rows have been processed

Tag & Non-Hierarchical Taxonomy Matrix

Since v1.1.25, Matrix Mode also supports post tags and non-hierarchical taxonomies including WordPress post tags. A single CSV row imports tag translations across all WPML languages simultaneously.

WooCommerce global attributes (pa_*): The shared path is the default: use a plain pa_color column when every product language should use the same term. Shirely 1.3.0 can also use language-suffixed columns such as pa_color|en and pa_color|de when you explicitly enable Translate global attributes (WCML Matrix opt-in). This applies only to Product Matrix imports and only when the attribute taxonomy is already configured as translatable in the supported WPML/WCML stack. Shirely does not change that configuration for you; review any preflight warning and verify the terms and variations in every language.

sku,title|en,title|pl,post_tag|en,post_tag|pl,price
SHIRT-001,Blue Shirt,Niebieska Koszula,"summer,new","lato,nowość",29.99

Separate multiple tags with a comma inside the cell. Quote the cell in your CSV when it contains commas (as shown above).

CSV Format

A Matrix CSV uses pipe-separated language codes in column headers. Any column with a |lang suffix is treated as a translatable field.

sku,title|en,title|pl,description|en,description|pl,price,stock_quantity
DRILL-100,Power Drill,Wiertarka,A powerful 18V drill,Mocna wiertarka 18V,149.99,25

Which fields can be translated

• title|en — Product name
• description|en — Full description
• short_description|en — Short description
• slug|en — URL slug

Fields like price, sku, stock_quantity, and weight are shared across languages.

Language Columns

Language codes must match your WPML configuration exactly. Use en, not en_US.

05 Variable Products

CSV Structure

Variable products require a type column to distinguish between parent products, variations, and simple products.

Parent & Variation Rows

Variations link to their parent via the parent_sku column. The parent row defines the variable product, and subsequent variation rows reference it.

type,parent_sku,sku,name,price,pa_color,pa_size
variable,,TSHIRT,T-Shirt,,,
variation,TSHIRT,TSHIRT-RS,T-Shirt Red S,29.99,Red,Small
variation,TSHIRT,TSHIRT-RM,T-Shirt Red M,29.99,Red,Medium
variation,TSHIRT,TSHIRT-BS,T-Shirt Blue S,34.99,Blue,Small
variation,TSHIRT,TSHIRT-BM,T-Shirt Blue M,34.99,Blue,Medium

Row order matters. The parent row must appear before its variation rows in the CSV file.

Key Rules

• Each variation must have a unique sku.
• The parent_sku column for variations must match the parent’s sku exactly.
• The parent row’s type must be variable.
• Leave parent_sku empty for parent and simple products.
• Price, stock, and weight are set per variation, not on the parent.

Attributes

WooCommerce product attributes use the pa_ prefix in CSV column headers.

SEO & Meta Fields

A mapped CSV column prefixed with meta_ is written as WordPress post meta. This covers Yoast SEO, Rank Math, custom post meta and simple ACF values stored as ordinary post meta.

How it works

The meta key written to the database is the column header with the meta_ prefix stripped. For example, the column meta__yoast_wpseo_title writes to the meta key _yoast_wpseo_title.

sku,title,meta__yoast_wpseo_title,meta__yoast_wpseo_metadesc
SHIRT-001,Blue Shirt,Blue Shirt | My Store,The ultimate blue shirt for summer.

Yoast SEO field reference

Rank Math field reference

Other custom meta fields

The meta_ prefix works for any post meta key. For example, meta_my_custom_field writes to the my_custom_field meta key.

06 Exporting Data

Standard Export

Matrix Export

Matrix Export generates a WPML-aware CSV with language-suffixed columns for editing and later Matrix import. Three one-click export cards are available:

• Product Matrix Export — Exports all products with translations as pipe-separated language columns.
• Posts & Pages Matrix Export — Exports the selected post, page or custom post type with translations.
• Taxonomy Matrix Export — Exports the selected taxonomy with translations and hierarchy data where applicable.

Filters & Fields

07 Google Sheets

Shirely can import from and export to Google Sheets using your own Google Cloud service account. The Google Sheets page provides deliberate, on-demand runs; Automation can schedule supported imports and catalog exports. Neither workflow is a live or two-way connection.

Setup is a one-time process: create a service account in Google Cloud, connect it to Shirely, and share each sheet you want to use with that account.

For a task-oriented overview of both directions, see connecting WooCommerce with Google Sheets.

Step 1 — Create a service account in Google Cloud

Step 2 — Connect the key to Shirely

Step 3 — Share your sheet with the service account

A service account is a separate Google identity. It only sees sheets shared with it — just like sharing with a colleague.

Step 4 — Import and export

Open Shirely → Google Sheets. Once a credential is connected you will see the service account email and connection status.

Saved slots: what is stored and refreshed

Save a sheet once, then use that slot for later imports or exports. The slot stores the sheet URL, range and content type. Import and export use separate slots and separate actions.

If you rename the sheet tab, update the saved range before the next run. Shirely does not automatically select a renamed tab.

08 Automation

Automation in Shirely 1.3.0 turns a repeatable import or catalog export into a saved slot. A slot stores the source or destination plus the settings needed for that job. You can run it deliberately with Run now, leave it manual, or assign one of the standard WP-Cron schedules.

Open Shirely → Automation. Import slots and export slots are separate because they store different fields and use different execution paths.

Create or edit an import slot

1. Under Import slots, open Add / edit import slot.
2. Enter a unique slot key. Saving another definition with that key updates the existing slot.
3. Choose the source type: Google Sheets, Remote CSV URL, or Inbox.
4. Enter the source. A remote CSV must be publicly reachable over HTTP(S). An inbox source is a bare .csv filename inside Shirely’s protected drop directory.
5. Choose the target post type or taxonomy and, for a non-Matrix import, the language. Matrix headers carry their own languages.
6. Leave the schedule at Manual runs only, or choose Hourly, Twice daily, or Daily.
7. Save the slot, then review its row before the first run.

Source-specific fields appear only when they apply. Google Sheets adds a sheet URL and tab/range; Remote CSV uses a public URL; Inbox uses a filename from the protected drop directory. The post type, taxonomy, language and Matrix options also change which configuration fields are relevant.

Create or edit an export slot

1. Under Export slots, open Add / edit export slot.
2. Enter a unique slot key and choose a supported catalog entity: products, product categories, or posts/custom post types.
3. Enter the destination Google Sheet URL and optional tab/range.
4. Choose a manual or WP-Cron schedule and save the slot.

Automated export in 1.3.0 publishes to Google Sheets. The target sheet must be shared with the configured Service Account as Editor. Scheduled export is limited to supported catalog data; orders, customers, coupons, reviews and subscriptions remain deliberate manual exports.

Run now and schedules

Run now starts the selected slot through the same headless import/export pipeline used by WP-Cron and WP-CLI. Each slot is one complete run: it is not split into independently scheduled sub-jobs. Shirely’s Batch Size, memory and execution-time settings also apply to Automation.

Use Run History as the completion gate

Do not treat a click, cron event or started request as proof that the job finished. Check Run History after every important run. It records the slot, direction, trigger, start time, status, created/updated/skipped/error counts and available details.

After a failure, first inspect the error detail and the destination. Imports can save completed rows before a later error, and a Google Sheets publish can have its own durable state. Do not repeatedly click Run now. Confirm whether the previous run finished, correct the source, credentials, permissions or server condition, and test a small run before resuming production work.

WP-Cron limits and the WP-CLI alternative

WP-Cron is traffic-driven. On a low-traffic site, an hourly, twice-daily or daily slot can start later than expected. It is not a precise scheduler, and a long slot still runs as one cron event that can meet host request limits.

For large imports or jobs that must start at a predictable time, use system cron with WP-CLI. A system administrator can either run due WordPress cron events or call the Shirely slot directly:

*/5 * * * * wp --path=/path/to/wordpress cron event run --due-now
0 3 * * * wp --path=/path/to/wordpress shirely slot run nightly-catalog

The direct wp shirely slot run <slot-key> form avoids a PHP web-request time limit and still writes the run result to Run History.

Plan WPML/WCML-writing imports sequentially

This warning is about avoiding an unusual overlap between separate data-changing runs. A normal single import, started after the previous one has completed, is the intended workflow.

09 Settings

Performance & Safety

These performance settings apply to the import wizard and to Automation. A schedule does not bypass the server’s memory, PHP execution or web-request limits.

Data Maintenance

Import Defaults

Two optional defaults for newly created items. Both apply only when the CSV row does not supply the value itself.

10 Troubleshooting

“Parent ID not yet imported — saved as root item. Will link when parent is imported.”

A child category appeared before its parent row. Shirely temporarily saves it at the root and runs a closing hierarchy pass after processing the file. Verify the resulting tree in every language when the import completes.

“Matrix ID is missing; update matching will be skipped for this row.”

The row has no Matrix Source ID mapped, so Shirely cannot match it through the internal _mie_ref_id. Product matching may still use the configured SKU, Product ID or Product Title strategy. For repeatable cross-store product imports, use a stable SKU.

“Matrix source ID is missing; _mie_ref_id will not be saved for this row.”

No source reference ID was found, so the internal _mie_ref_id value will not be saved for this item. Check the selected matching strategy before a later re-import.

“Matrix source ID was not mapped; using the raw file value.”

The source ID column was found in the file but was not explicitly mapped. Shirely uses the raw file value for this reference; verify that the value is the intended stable identifier.

“Product already exists; skipped due to ‘Only Create’ mode.”

You selected Only Create in the mapping screen. Shirely found a matching product and skipped it. Select Create & Update for a run that should update matched products.

“⚠️ LANGUAGE MISMATCH” banner

Your WordPress admin panel language flag (top bar) does not match the language you selected in the import wizard. This can cause products to be created in the wrong language context in WPML. Click the language flag in the top-right corner of the admin bar and switch it to match your import language, then re-start the import.

“Term X has no [language] translation (TRID Y), using [fallback] fallback”

A product is being assigned to a category that has no translation in the target language. Shirely falls back to the default-language term. Create the missing WPML translation, then back up and test the corrected assignment on a small sample before a wider taxonomy re-import.

“Term X has no [language] translation; strict_language prevents fallback”

Same situation as above, but Strict Language mode is active, which disables the fallback. The product will not be assigned to that category for the missing language. Create the category translation in WPML and re-import to resolve.

“Multiple terms match meta key/value — using lowest term_id”

Two or more categories share the same lookup value (e.g. the same external ID or slug). Shirely picks the one with the lowest database ID (the oldest) and continues. To avoid ambiguity, ensure each category has a unique identifier in your source data.

Import Issues

Import stuck at 0%

This usually indicates a server timeout or a conflict with another plugin. Try these steps:

• Reduce the Batch Size in Shirely → Settings to 5.
• Increase the Request Delay to 1000 ms.
• Check the Dashboard system-health result for max_execution_time; Shirely’s health target is 60 seconds or unlimited.
• Temporarily deactivate other plugins to rule out conflicts.

Products created but no translations

Matrix Mode is detected automatically. Verify that WPML is active and that the headers use pipe-separated language suffixes (for example title|en and title|pl) matching the language codes configured in WPML. The mapping screen should show the Matrix Mode badge.

Variable product has no variations

Check that the parent row appears before its variation rows in the CSV. Verify the parent_sku value in each variation row matches the parent’s sku exactly. Also confirm that the type column contains variable for the parent and variation for each child.

Export Issues

Export file is empty

Verify that your selected content type has published items. Check that your filters are not too restrictive. Try exporting without any filters to confirm the export engine is working.

WPML Issues

“WPML not detected” message

Multilingual features — Matrix Mode, translation linking, language columns — require WPML Multilingual CMS (the core plugin) to be active; the rest of Shirely works without it. If you have WPML installed but not activated, go to Plugins and activate it. Ensure you are running WPML version 4.5 or higher.

Translations are not linked

Translation linking runs during a Matrix import; there is no setting to enable it. Check that WPML is active, the mapping screen showed the Matrix Mode badge, and the headers use the exact WPML language codes. Then verify the translation relationships in the relevant WordPress or WooCommerce edit screens and review the import log.

During category import you may see a message like:

Row 280 (ID 20885): Parent ID "30883" (lang: en) not yet imported — saved as root item. Will link when parent is imported.

This happens when a child category appears before its parent row. Shirely temporarily stores the child at the root and applies parent links during the closing hierarchy pass.

If categories remain orphaned after the run, do not blindly re-import a full taxonomy export. Back up the database, verify the source and parent identifiers, and test the corrected import on a small sample first.

Debug Mode

For advanced troubleshooting, enable WordPress debug logging by adding the following to your wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

After enabling debug mode, reproduce the issue and check wp-content/debug.log for error messages. Shirely logs its operations with a [Shirely] prefix for easy filtering.

11 Known issues

Large WPML category trees on servers with short FastCGI timeouts

When WPML and WooCommerce Multilingual are active, a hierarchical Matrix import of product categories can complete its category writes but still show “Import Failed” in the browser if the server ends the request during WPML/WCML hierarchy reconciliation.

In Shirely’s MAMP regression environment, the same browser workflow passed at 5,000 total product_cat terms and failed at 6,000. This is a measured environment-specific range, not a universal category limit: the cost also depends on the existing category hierarchy and translation data. These figures are totals across all languages, not per-language counts.

Before retrying after a timeout, verify the imported categories and their translations. For this workflow, configure the web server’s FastCGI response budget above 30 seconds and test the full category tree on staging first. Increasing the browser-side request timeout alone does not override a shorter server-side FastCGI limit.

12 FAQ