Translation by filename

Managing multilingual Hugo sites translated by filename.

This approach is similar to a non-multilingual configuration. Related content stays together, making it easier to see inconsistencies across languages. However, it may be harder to find or distinguish specific files.

Hugo calls this Translation by filename. You will need to specify a language per file, as an extension prefix (e.g. content/blog/my-post.es.md).

The best practice here is to define a collection for each folder of related files (e.g. Posts, Pages, Staff Members). Each collection contains the files from all languages.

You'll need a custom create path here to include the language code in new filenames.

Here's an example with Pages and Posts:

content/
 about.md
 about.es.md
 about.fr.md
 blog/
    first-post.md
    first-post.es.md
    first-post.fr.md
cloudcannon.config.yaml
copied
collections_config:
  pages:
    path: content
    filter: strict
  posts:
    paths: content/blog
    create:
      path: '[relative_base_path]/{title|slugify}{suffix}.md'
      extra_data:
        dot: .
        suffix: '{dot|if=language}{language|lowercase}'
      _inputs:
        language:
          type: select
          options:
            allow_empty: false
            value_key: lang_code
            values:
              - name: English
                lang_code: 
              - name: Spanish
                lang_code: es
              - name: French
                lang_code: fr

When you browse a collection in CloudCannon, all files within that folder will be shown by default. Applying the strict filter to a collection instead limits the UI to show only the files that exactly match that collection.

In this case, it prevents files from the Posts collection in the content/blog/ subdirectory from appearing when browsing the pages collection.

The create option controls the filename and path when creating new content files.

Placeholders are specified inside curly braces, and editors will be prompted to supply values for them when saving the file for the first time. If the placeholders share names with top level inputs in your front matter, editing them in the prompt also changes those values in the file contents.

In this case, editors will be prompted to add a title and language when saving the file for the first time.

When "English" is chosen, no language code is added to the filename - in this example English is the default language, and Hugo has no extra filename suffix for the default language.

This _inputs entry restricts the language editors can choose to one of the specified languages. language would be a text input without this, which would work but is more prone to errors.

By selecting from a list of objects and setting the value_key, we allow the editor to select the option "English" while saving an empty value.

cloudcannon.config.json
copied
{
  "collections_config": {
    "pages": {
      "path": "content",
      "filter": "strict"
    },
    "posts": {
      "paths": "content/blog",
      "create": {
        "path": "[relative_base_path]/{title|slugify}{suffix}.md",
        "extra_data": {
          "dot": ".",
          "suffix": "{dot|if=language}{language|lowercase}"
        },
        "_inputs": {
          "language": {
            "type": "select",
            "options": {
              "allow_empty": false,
              "value_key": "lang_code",
              "values": [
                {
                  "name": "English",
                  "lang_code": null
                },
                {
                  "name": "Spanish",
                  "lang_code": "es"
                },
                {
                  "name": "French",
                  "lang_code": "fr"
                }
              ]
            }
          }
        }
      }
    }
  }
}

When you browse a collection in CloudCannon, all files within that folder will be shown by default. Applying the strict filter to a collection instead limits the UI to show only the files that exactly match that collection.

In this case, it prevents files from the Posts collection in the content/blog/ subdirectory from appearing when browsing the pages collection.

The create option controls the filename and path when creating new content files.

Placeholders are specified inside curly braces, and editors will be prompted to supply values for them when saving the file for the first time. If the placeholders share names with top level inputs in your front matter, editing them in the prompt also changes those values in the file contents.

In this case, editors will be prompted to add a title and language when saving the file for the first time.

When "English" is chosen, no language code is added to the filename - in this example English is the default language, and Hugo has no extra filename suffix for the default language.

This _inputs entry restricts the language editors can choose to one of the specified languages. language would be a text input without this, which would work but is more prone to errors.

By selecting from a list of objects and setting the value_key, we allow the editor to select the option "English" while saving an empty value.

cloudcannon.config.cjs
copied
module.exports = {
  collections_config: {
    pages: {
      path: "content",
      filter: "strict"
    },
    posts: {
      paths: "content/blog",
      create: {
        path: "[relative_base_path]/{title|slugify}{suffix}.md",
        extra_data: {
          dot: ".",
          suffix: "{dot|if=language}{language|lowercase}"
        },
        _inputs: {
          language: {
            type: "select",
            options: {
              allow_empty: false,
              value_key: "lang_code",
              values: [
                {
                  name: "English",
                  lang_code: null
                },
                {
                  name: "Spanish",
                  lang_code: "es"
                },
                {
                  name: "French",
                  lang_code: "fr"
                }
              ]
            }
          }
        }
      }
    }
  }
};

When you browse a collection in CloudCannon, all files within that folder will be shown by default. Applying the strict filter to a collection instead limits the UI to show only the files that exactly match that collection.

In this case, it prevents files from the Posts collection in the content/blog/ subdirectory from appearing when browsing the pages collection.

The create option controls the filename and path when creating new content files.

Placeholders are specified inside curly braces, and editors will be prompted to supply values for them when saving the file for the first time. If the placeholders share names with top level inputs in your front matter, editing them in the prompt also changes those values in the file contents.

In this case, editors will be prompted to add a title and language when saving the file for the first time.

When "English" is chosen, no language code is added to the filename - in this example English is the default language, and Hugo has no extra filename suffix for the default language.

This _inputs entry restricts the language editors can choose to one of the specified languages. language would be a text input without this, which would work but is more prone to errors.

By selecting from a list of objects and setting the value_key, we allow the editor to select the option "English" while saving an empty value.

Open in a new tab