Translatable Slugs

The Translatable Slugs app gives a folder or story its own slug in each language configured under Settings → Internationalization. It complements field-level translation, and pairs with the Advanced Paths app when you need a custom URL structure.

When a language has no translated slug, Storyblok falls back to the slug of the default language.

Features

• Define a slug per language for folders and stories.
• Fall back to the default language when a translated slug is missing.
• Read localized slugs and their publication status from the Content Delivery API.
• Create, update, and delete translated slugs through the Management API.

Setup

Install the app, then set the translated slugs in one of two places:

• In the Visual Editor, open the Config section and use the Languages menu next to the default slug to set a name and slug per language.
• In the Content section, select a story or folder, open its settings, and use the Languages menu in the dialog.

Content Delivery API

The Content Delivery API returns the localized slugs of each folder and story in the translated_slugs array of the story and the alternates array of the link object. The value of the published property of each translated slug depends on the Publish translations individually setting in Settings → Internationalization and on the story’s status. The value also depends on whether the story is a root page (is_startpage: true) and whether a translated slug exists:

Publish translations individually	Page	Translated slug	Draft	Published	Unpublished
Enabled	Non-root	Set	null	true	false
Enabled	Non-root	Not set	null	null	null
Enabled	Root	Set	null	true	false
Enabled	Root	Not set	null	true	null
Disabled	Non-root	Set	false	true	false
Disabled	Non-root	Not set	null	null	null
Disabled	Root	Set	false	true	false
Disabled	Root	Not set	false	true	false

Management API

The Update a story endpoint (PUT) creates, updates, and deletes translated slugs. The Create a story endpoint (POST) only adds new translated slugs. A single PUT request can mix all three operations in the translated_slugs_attributes array of the story:

• Create: omit id and provide lang and slug, and optionally name and published.
• Update: include the existing id together with the fields to change.
• Delete: include the existing id and set _destroy to true.

The translated_slugs field of the story response contains the IDs that update and delete operations require.

Further resources

Retrieve a single story in the Content Delivery API

Translatable Slugs in the app directory