Live article: https://www.storyblok.com/faq/how-to-set-an-advanced-path-based-on-translated-slugs
- FAQ
- How to set an advanced path based on translated slugs
Introduction
This FAQ provides a step-by-step guide on setting up advanced paths with translatable slugs based on the editor language in multi-language space setups. The implementation involves using the Squirrelly helper function @activeTranslatedSlug
, which is a specific helper in Storyblok. This helper simplifies the process of handling translated slugs and fallback scenarios.
Prerequisites
Before using the @activeTranslatedSlug
helper, ensure that you have both the have both the advanced path app and the translatable slug app installed.
Usage Examples
Basic Usage
To use the helper with default settings, which tries to find the translated slug based on the current editor language:
{{ @activeTranslatedSlug({ it }) /}}
Fallback to simpler slugs
If you want to fallback to other translated slugs when an exact match between the set editor language and the translated slug is not found (for example, 'en-US'
becomes 'en'
), use the fallbackSlugs
parameter, which is by default set to true
:
{{ @activeTranslatedSlug({ it, fallbackSlugs: true }) /}}
If you don't want the fallback, you need to set it to false.
{{ @activeTranslatedSlug({ it, fallbackSlugs: false }) /}}
Prepending Strings to the returned slug
By default, the helper prepends a slash /
to translated slugs:
{{ @activeTranslatedSlug({ it, prependString: '/' }) /}}
You can prepend other strings to the generated slugs too:
{{ @activeTranslatedSlug({ it, prependString: '/new/' }) /}}
Or you can remove the default behaviour of prepending a slash /
by passing an empty string:
{{ @activeTranslatedSlug({ it, prependString: '' }) /}}
Functionality Overview
The @activeTranslatedSlug
helper performs the following tasks:
- If the editor language isn't set (default language), it returns the original
story.slug
orfolder.slug
- If the editor language is set, it looks for a match in the
story.translated_slugs
orfolder.translated_slugs
array. - If a matching translated slug is found, it's returned.
- If no matching translated slug is found and
fallbackSlugs
istrue
, it tries to find a translated slug using a simplified version of the language code (for example,'en-US'
becomes'en'
) - If no translated slug is found using either the full or simplified language code, it returns the original
story.slug
orfolder.slug
@activeTranslatedSlug Parameters
it
- type:
object
- required:
true
- description: the context of the advanced path templates, normally it contains
story
,lang
,folder
(only for folders paths),branch_id
,env_location
andenv_name
- type:
prependString
- type:
string
- required: false
- default:
'/'
- description: a string that is prepended to the found translated slug.
- type:
fallbackSlugs
- type:
boolean
- required: false
- default:
true
- description: With this parameter you can control whether it should fallback on other simpler version of the language code, e.g.
'en-US'
becomes'en'
to find a translatable slug
Template Equivalent
If you were to write the Squirrelly template without using the helper, it would look something like this:{{ @if(it.lang) }}/ {{ @each(it.story.translated_slugs) => t_slug, index }} {{ @if(t_slug.lang === it.lang) }} /{{ t_slug.slug }} {{ #else }} {{ it.story.slug }} {{ /if }} {{/each}} {{ #else }} {{ it.story.slug }} {{ /if }}
This helper simplifies and abstracts away the complexity of handling translatable slugs together with the advanced paths app in your Squirrelly templates.- type: