Update Translated Slugs Using Agents

In today's global landscape, delivering localized content to users is more important than ever. How can you ensure that native users find the appropriate page on your website in their own languages? This is where localized URLs become essential. Localized URLs for each language version of your website enhance both Search Engine Optimization (SEO) and user experience.

When you manage your content in Storyblok, you can use the Translatable Slugs app. This app enables you to create a unique URL for each language in your stories and folders. It is available for the Growth plan and higher tiers.

However, it is a challenge when you manage translated slugs manually within your space in Storyblok. It is time-consuming and difficult to scale, especially if you have multiple languages or many stories. The good news is that the Storyblok Management API offers an efficient solution by enabling you to update translated slugs across your space in bulk.

This tutorial shows how to add and update translated slugs using the Management API, and how to use AI agents such as Claude to automate the process. It also shows how to create your own Storyblok-specific skills, a powerful way to turn repetitive content tasks into reusable, automated workflows.

Why use the Translatable Slugs app

Translated slugs help maintain brand consistency across regions, since different regions may prefer different slugs even within the same language. You can set region-specific URLs that align with the local brand tone. For instance, a page slug like /deals is used in English (EN), while EN-UK uses /offers, and EN-US uses /promotions.

These are common use cases for translatable slugs:

• Marketing campaigns: When you run multilingual marketing campaigns, using translatable slugs ensures that all URLs are relevant and appealing to each target demographic, increasing engagement and conversion rates.
• E-commerce platforms: Online stores can use translatable slugs to create SEO-friendly URLs in multiple languages. This helps improve visibility in search engines and provides a localized shopping experience for users.
• Multilingual blogs: Bloggers who write in several languages can use translatable slugs to maintain a consistent structure in their URL. It enhances readability and improves indexing by search engines.
• Software applications: Apps that serve a global audience can benefit from translatable slugs in their URLs, ensuring that links shared by users are understood by people in various regions.

How the Translatable Slugs app works

The Translatable Slugs app allows you to define language-specific slugs and names for each story and folder in Storyblok. For example, a page slug like /contact in English can be set as /contacto in Spanish, improving SEO, user trust, and discoverability in each language.

To add special characters as a translated slug in your space, open Settings → Space, and enable the Allow special characters in slugs toggle. Remember to URL encode the slugs afterward.

The translated slugs become the URL paths used when visitors access a localized version of the site. Use clear, consistent slugs so they work well for SEO.

To implement translatable slugs in your frontend implementation using the Content Delivery API, refer to the Build a Multilingual Website with Storyblok and Astro tutorial.

Add translated slugs using the Management API

To add translated slugs, you need to include a translated_slugs_attributes array field in your request payload when you update a story. Each item in this array should specify the language code (lang), the translated slug (slug), and the translated name (name).

This example shows how to add a translated slug commercialisation and translated name Commercialisation to the Marketing story in the French language.

// ...

import { createManagementApiClient } from "@storyblok/management-api-client";

const client = createManagementApiClient({
  personalAccessToken: process.env.STORYBLOK_PERSONAL_ACCESS_TOKEN,
  spaceId: process.env.STORYBLOK_SPACE_ID,
  region: process.env.STORYBLOK_REGION,
});

// Add a new translated slug to a story
const { data, error } = await client.stories.update(
  process.env.STORYBLOK_STORY_ID,
  {
    body: {
      story: {
        name: "Marketing",
        slug: "marketing",
        translated_slugs_attributes: [
          {
            lang: "fr", // language code
            slug: "commercialisation", // translated slug
            name: "Commercialisation", // translated name
          },
        ],
      },
    },
  }
);

if (error) {
  console.error(error);
} else {
  console.log(data.story);
}

Update existing translated slugs using the Management API

To update a translated slug with the Management API, you first need to get the id of the translated slug you want to modify.

You can retrieve the translated slug id when you fetch the story using the Management API.

In the API response, look for the translated_slugs field. This contains an array of all translated slugs for the story, including their ids, names, and language codes.

Each translated slug includes an id and the lang fields. Use the id that matches the language you want to modify.

Here is an example of how to retrieve an existing translated slug id by fetching a story:

// 1. Fetch the story with Management API to get the existing
//    translated slug ID that needs to be updated

const { data, error } = await client.stories.get(
  process.env.STORYBLOK_STORY_ID
);

if (error) {
  console.error("Error retrieving translated slug:", error);
} else {
  console.log("Existing translated slug:", data.story.translated_slugs);
}

Once you have the translated slug id, you can proceed to update the translated slugs. In your request payload, include the translated slug id in the translated_slugs_attributes array, along with the updated translated name and translated slug. Storyblok uses the translated slug id to identify which translated slug needs to be updated.

This example updates the French existing translated slug to marketing and the name to Marketing, because French also uses marketing.

// 2. Update the translated slug using the retrieved translated slug ID

const { data, error } = await client.stories.update(
  process.env.STORYBLOK_STORY_ID,
  {
    body: {
      story: {
        name: "Marketing",
        slug: "marketing",
        translated_slugs_attributes: [
          {
            id: 227323467977689, // translated slug ID
            lang: "fr", // language code
            slug: "marketing", // translated slug
            name: "Marketing", // translated name
          },
        ],
      },
    },
  }
);

if (error) {
  console.error("Error updating translated slug:", error);
} else {
  console.log("Translated slug updated:", data.story);
}

Automate translated slug updates using AI agents

The previous examples add translated slugs manually in code. Instead, AI agents can translate the slugs into any language you specify, then add them directly to your stories and folders or update existing translated slugs.

To provide an AI agent with the necessary context to understand the workflow for updating translated slugs in Storyblok, we will use the Agent skills approach. Agent skills are reusable instructions that help AI agents perform specialized tasks. In this case, the skill is designed to update translated slugs while seeking your approval before making any changes.

How the skill works

The update-translated-slugs skill adds or updates translated slugs and translated names for existing Storyblok stories and folders, using the Management API and the Translatable Slugs app. To use this skill in your own environment, you can install the skill with the skills CLI:

npx skills add https://github.com/storyblok/tutorials/tree/main/build/update-translated-slugs

This installs the skill into your current project. Add -g to install it for all your projects instead.

If you prompt an AI agent with "Translate the slugs for the categories folder into French," it loads the skill and proceeds through four stages.

Setup

• Check the .env file. The agent confirms that the Management API token and Space ID are set in .env file, SB_REGION is optional and defaults to eu.
• Ask about Translatable Slugs app. The agent asks whether the Translatable Slugs app is installed in the space. If it isn't, it stops and tells you to install it.
• Install the dependencies. The agent navigates to the scripts/ folder and runs npm install if node_modules is missing.

Find the language and the stories

• Fetch the languages. The agent runs node fetch-languages.js. French was named in the prompt, so the agent doesn't ask which language to translate slugs into. It takes the matching code from the output, such as fr. If French isn't configured in the space, the agent stops and points you to add the language in your space settings.
• Fetch the folder. The agent runs node fetch-stories.js --starts-with categories, which returns the folder and everything inside it.
• Ask about the scope of translation. Because you named a folder, the agent asks whether you mean the folder only, the stories in it, or both. The answer changes the URLs:
  • Folder only: actualites/my-post
  • Stories only: news/mon-article
  • Both: both segments are translated.
• Root stories. A folder's start page (is_startpage: true) only gets a translated name. It can't have its own translated slug.

Translate and review the slugs

• Translate slugs. The agent translates slugs and names into French. Slugs may only use a–z, A–Z, 0–9, _ and -, so accents are removed (for example, catégories becomes categories). To allow special characters in your slugs, you’ll need to enable it in your space Settings → Space, and enable the Allow special characters in slugs toggle. Then you can modify the skills to support it.
• Review the translations. The agent writes scripts/translations.json with lang: "fr" on every entry. It shows you each original and translated slug and name, and you can reply with changes or edit the file yourself.

Preview, approve and apply the changes

• Dry run. The agent re-reads translations.json file in case you edited it, then runs node update-translated-slugs.js translations.json --dry-run. The output lists which translated slugs will be added (+) and which existing ones will be overwritten (~ old → new).
• Your approval. The agent doesn’t update anything in your space until you explicitly approve the dry run.
• Apply the changes. The agent runs the script without --dry-run and reports how many slugs were added, updated, and failed.

When using skills to automate bulk updates for translated slugs in your space—whether for stories or folders—it's important to keep in mind a few key points. Updating translated slugs changes the public URL, so make sure you set up redirects. Additionally, remember to publish the new translated slug and activate the redirects simultaneously.

Takeaways

The Management API allows you to add and update translated slugs across your space in bulk. An AI agent skill takes this a step further by automating the entire workflow. It finds the stories, translates the slugs, and applies them, while seeking your approval at each key step. This way, you can focus on reviewing the translations instead of entering them manually. Remember, since translated slugs update public URLs, be sure to set up redirects before you publish.