Skip to main content

Troubleshooting

The page loads but nothing translates​

Check the basics first:

  • the SDK script actually loads
  • the project key is present
  • the project key belongs to the environment you are calling
  • the target locale is part of the supported locales for the project

The wrong language is selected​

For JavaScript SDK and storefront integrations, verify:

  • urlMode is correct (query or path)
  • languageParam matches your URL strategy when using query mode
  • supported locales include the value you are trying to load
  • Shopify locale fallback is only enabled when you intend to use it

The API returns 404 Project not found​

Most common causes:

  • wrong project key
  • project belongs to another environment
  • archived or inactive project

The API returns 429​

Kalima enforces layered rate limits. Back off and retry rather than hot-looping requests. If the traffic pattern is expected and sustained, contact Kalima with:

  • project key
  • endpoint used
  • approximate request volume
  • whether the issue is production or QA only

Phrase extraction fails​

For POST /phrases/batch-extract, confirm:

  • project key is valid
  • the project has the required feature enabled
  • payload size is within limits
  • phrases contains no more than 500 items
  • request body fields match the documented shape in API reference

WordPress is installed but translations do not appear​

Check:

  • plugin is active
  • project key is set under Settings -> Kalima
  • API base URL is valid
  • SDK override URL uses an allowed HTTPS host unless on localhost
  • default language and supported locales are configured correctly

Shopify app saves but storefront behavior is wrong​

Check:

  • app settings were saved successfully
  • theme embed is enabled
  • storefront is using the intended API base URL
  • hosted SDK script URL is valid
  • use_shopify_locale matches your storefront strategy
  • hreflang and URL mode settings match your SEO and routing approach

CI or automation cannot find translation files​

If you are using the advanced GitHub Actions workflow, verify:

  • translation files are in expected folders such as locales/, i18n/, or translations/
  • .locale/config.json points to the correct paths
  • repository secrets use KALIMA_PROJECT_KEY and KALIMA_API_URL

Support

Need help shipping this integration?

If you hit a blocker, contact Kalima with your project key, target environment, and a short description of what failed.

Contact KalimaEmail info@kalima.digital