---
title: Translatable Slugs
description: The Translatable Slugs app gives folders and stories a different slug per language.
url: https://www.storyblok.com/docs/apps/translatable-slugs
---

# 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](/docs/concepts/internationalization), and pairs with the [Advanced Paths app](/docs/apps/advanced-paths) 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](/docs/api/content-delivery/v2/stories/retrieve-a-single-story) and the `alternates` array of the [link object](/docs/api/content-delivery/v2/links/retrieve-a-single-link). 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](/docs/api/management/stories/update-a-story) endpoint (`PUT`) creates, updates, and deletes translated slugs. The [Create a story](/docs/api/management/stories/create-a-story) endpoint (`POST`) only adds new translated slugs. A single `PUT` request can mix all three operations in the [`translated_slugs_attributes`](/docs/api/management/stories/the-story-object) 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](/docs/api/content-delivery/v2/stories/retrieve-a-single-story)

[Translatable Slugs in the app directory](https://www.storyblok.com/apps/translatable-slugs)

## Pagination

-   [Previous: Task Manager](/docs/apps/task-manager)
-   [Next: Trash Bin](/docs/apps/trash-bin)
