Troubleshooting

This page is a technical reference covering how the app processes names, what makes a name non-translatable, and the prerequisites for correct operation. We have no support ticket history to identify “common issues” — if you run into something not covered here, contact us directly.

Name validation rules

The app accepts a name for declension only if it passes a regex check (/^[\wá-ž]{2,}$/i). Names that fail this check are marked non-translatable and the original value is kept as the fallback — this is intentional behavior, not a bug.

Names that pass (accepted for declension):

• Standard Czech and Latin letters (a–z, á–ž, A–Ž)
• Digits and underscores

Names that fail (non-translatable, original value kept):

Character	Example
Hyphen	Anne-Marie
Space	van den Berg
Apostrophe	O'Brien
Non-Latin script	李偉, محمد
Fewer than 2 characters	A

When a name is non-translatable, the addressing and last-name-addressing metafields receive the original name unchanged, and gender is set to unknown.

Metafield keys

The app writes to three metafields in the czech-names-app namespace, type single_line_text_field:

Key	Content
czech-names-app.addressing	Declined first name (e.g. “Jano”)
czech-names-app.last-name-addressing	Declined last name (e.g. “Nováková”)
czech-names-app.gender	male, female, or unknown

To verify values in Shopify admin: open a customer profile, scroll to the Metafields section, and look for the czech-names-app namespace.

Caution

When referencing metafields in Liquid, always use bracket notation — the hyphen in the namespace name breaks dot notation:

{{ customer.metafields['czech-names-app'].addressing }}  {# correct #}
{{ customer.metafields.czech-names-app.addressing }}     {# broken — hyphen is parsed as subtraction #}

Billing prerequisite

The app silently skips all webhook processing if billing is not active. If metafields are not appearing at all, check the subscription status first. In Shopify admin: Settings → Apps and sales channels → CZ Names. The app dashboard also shows “Billing is not enabled” when the subscription is inactive.

If billing lapsed or was never accepted at install, reactivate the subscription and then re-trigger processing by editing and saving a customer profile.

Klaviyo sync timing and limitations

The Klaviyo sync runs once per customer event (create or update). It does not retry automatically.

Klaviyo requires 3–5 minutes after customer creation before their profile is accessible via the Klaviyo API. If a customer is synced before their Klaviyo profile exists, the sync is permanently skipped for that event. The only way to re-trigger it is a subsequent customer update in Shopify.

The properties written to Klaviyo are:

• Czech addressing
• Czech last name
• Gender

See the Klaviyo Integration page for API key setup and required permissions.

Gender detection

Gender is detected by the external sklonovani-jmen.cz API using Czech linguistic conventions. The app has no internal gender logic — the API result is stored as-is.

• male or female — the API assigned a grammatical gender with confidence
• unknown — the name did not match Czech linguistic patterns (common for foreign names)

This value is linguistic gender used for grammatical addressing only (Pane / Paní / neutral). There is no setting to override it.

UI Extensions render nothing while loading

Extensions show blank while customer data is loading, and also show blank if the czech-names-app metafields do not yet exist on the customer. Customers created before the app was installed have no metafields — edit and save their profile to trigger processing.

Need help?

Contact us at integrace@soundsgood.agency. Include:

• Your store URL
• The customer first name and last name causing the issue
• What you expected and what actually happened
• A screenshot of the Metafields section on the customer profile (if relevant)