Enhancement: Create a new `{{locale}}` placeholder for i18n content

Create a new {{locale}} placeholder for i18n content and their preview paths.

And it might serve as a good groundwork for i18n improvements. Something like this would be beneficial: "previewPath": "{{localePath}}/{{pathToken.relPath}}".

{{locale}} should become its own placeholder which can be used in the preview path as well. Good feedback. I'll create a new issue for it to track it.

Originally posted by @estruyf in https://github.com/estruyf/vscode-front-matter/issues/806#issuecomment-2127741147

New {{locale}} placeholder can be used in the previewPath. For example: "previewPath": "{{locale}}/blog".

You can also ignore locales, for instance, if you do not want to include the en locale in the preview path, but all others are fine. Examples:

{{locale|ignore:en}}: ignore only en
{{locale|ignore:en,nl}}: ignore en and nl

@theinfinit feel free to give it a try.

To document

[x] Add the locale placeholder
[x] Add the documentation to ignore certain locales

Tested with beta v10.2.9236459.

For now, I can't get it to work 🫣

1. Simple case

// 👁️ — pages visible in the dashboard

$ tree content
src/
└── content/
    └── astro-content-collection/
        └── reference/
            └── 👁️ index.md
            └── 👁️ example.md
        └── de/
            └── reference/
                └── index.md // http://localhost:4321/de/reference/ ✅
                └── example.md // http://localhost:4321/de/example/ -> Expected http://localhost:4321/de/reference/example/
            👁️ index.mdx // http://localhost:4321/de/ ✅
        👁️ index.mdx

"frontMatter.content.i18n": [
    { "title": "English", "locale": "en", "path": "." },
    { "title": "Deutsch", "locale": "de", "path": "de" }
  ],
"frontMatter.content.pageFolders": [
  {
    "title": "Docs",
    "path": "[[workspace]]/src/content/docs/",
    "excludeSubdir": true,
    "previewPath": "{{locale}}",
    "defaultLocale": "en"
  },
  {
    "title": "Guides",
    "path": "[[workspace]]/src/content/docs/guides",
    "previewPath": "{{locale}}/guides",
    "defaultLocale": "en"
  },
  {
    "title": "Reference",
    "path": "[[workspace]]/src/content/docs/reference",
    "previewPath": "{{locale}}/reference",
    "defaultLocale": "en"
  }
],

2. Partially modified, complex configuration:

Under Showing: Docs filter in the dashboard, only English pages are visible. Pages from other languages aren't included in the dashboard at all.

"frontMatter.content.i18n": [
  { "title": "English", "locale": "en", "path": "." },
  { "title": "Deutsch", "locale": "de", "path": "de" },
  { "title": "Español", "locale": "es", "path": "es" }
],
"frontMatter.content.pageFolders": [
  {
    "title": "Root",
    "path": "[[workspace]]/src/content/astro-content-collection/",
    "previewPath": "{{pathToken.relPath}}/",
    "excludeSubdir": true,
    "defaultLocale": "en",
  },
  {
    "title": "Docs",
    "path": "[[workspace]]/src/content/astro-content-collection/docs/",
    "previewPath": "{{locale}}/docs/{{pathToken.relPath}}/", // 👈 added `{{locale}}`
    "excludeSubdir": true,
    "defaultLocale": "en",
    // Removed "locales": [...]
  },
  {
    "title": "Docs / Guides",
    "path": "[[workspace]]/src/content/astro-content-collection/docs/guides",
    "previewPath": "/docs/guides/",
    "defaultLocale": "en",
    "locales": [
      { "title": "English", "locale": "en" },
      { "title": "Deutsch", "locale": "de",    "path": "../../../de/docs/guides/" },
      { "title": "Español", "locale": "es",    "path": "../../../es/docs/guides/" },
    ],
  },
]

Preview path for localized page de/docs/manual-setup.md:

<!-- Received -->
http://localhost:4321/docs/manual-setup/

<!-- Expected -->
http://localhost:4321/de/docs/manual-setup/

Previous, working configuration:

"frontMatter.content.pageFolders": [
  {
    "title": "Root",
    "path": "[[workspace]]/src/content/astro-content-collection/",
    "previewPath": "{{pathToken.relPath}}/",
    "excludeSubdir": true,
    "defaultLocale": "en",
  },
  {
    "title": "Docs",
    "path": "[[workspace]]/src/content/astro-content-collection/docs/",
    "previewPath": "/docs/{{pathToken.relPath}}/",
    "excludeSubdir": true,
    "defaultLocale": "en",
    "locales": [
      { "title": "English",              "locale": "en" },
      { "title": "Deutsch",              "locale": "de",    "path": "../../de/docs/" },
      { "title": "Español",              "locale": "es",    "path": "../../es/docs/" }
    ],
  },
  {
    "title": "Docs / Guides",
    "path": "[[workspace]]/src/content/astro-content-collection/docs/guides",
    "previewPath": "/docs/guides/",
    "defaultLocale": "en",
    "locales": [
      { "title": "English",              "locale": "en" },
      { "title": "Deutsch",              "locale": "de",    "path": "../../../de/docs/guides/" },
      { "title": "Español",              "locale": "es",    "path": "../../../es/docs/guides/" },
    ],
  },
]

3. `{{locale}}` added to every `pageFolders` entry

Localized pages are not visible in the dashboard too. The only visible, localized page was from "Root" pageFolder.

Because of that, I tested preview for that page (de/index.md), and got http://localhost:4321/316/de/ (notice strange 316 subpath, which is not present anywhere).

"frontMatter.content.i18n": [
  { "title": "English", "locale": "en", "path": "." },
  { "title": "Deutsch", "locale": "de", "path": "de" },
  { "title": "Español", "locale": "es", "path": "es" }
],
"frontMatter.content.pageFolders": [
  {
    "title": "Root",
    "path": "[[workspace]]/src/content/astro-content-collection/",
    "previewPath": "{{locale}}/{{pathToken.relPath}}/",
    "excludeSubdir": true,
    "defaultLocale": "en",
  },
  {
    "title": "Docs",
    "path": "[[workspace]]/src/content/astro-content-collection/docs/",
    "previewPath": "{{locale}}/docs/{{pathToken.relPath}}/", 
    /* Also tested with: 
     * "previewPath": "{{locale}}/docs", 
     * but got the same "316" preview path: `http://localhost:4321/316/de/`
     */
    "excludeSubdir": true,
    "defaultLocale": "en",
  },
  {
    "title": "Docs / Guides",
    "path": "[[workspace]]/src/content/astro-content-collection/docs/guides",
    "previewPath": "{{locale}}/docs/guides/",
    "defaultLocale": "en",
  },
]

1. Simple case

There is a config issue with the folder paths. Your DE content should be located in src/content/astro-content-collection/reference/de/, not in src/content/astro-content-collection/reference/de/reference.

The results should all be as expected when configured like the first path.

2. Partially modified, complex configuration

Same issue as the first one. Your i18n content should be in src/content/astro-content-collection/docs/de/manual-setup.md, instead of src/content/astro-content-collection/docs/de/docs/manual-setup.md

3. {{locale}} added to every pageFolders entry

Fix coming up, this has to do with the date formatting on the pathname, but replaced the logic.

Hi Elio! I found some time to test beta v10.3.9501641.

This is the folder structure I worked with:

astro-content-collection: docs/ # root
├── pl/ # locale
│   ├── reference/
│   │   ├── example.md # Expected: http://localhost:4321/pl/reference/example/
│   │   └── index.md   # Expected: http://localhost:4321/pl/reference/
│   └── index.mdx      # Expected: http://localhost:4321/pl/
├── guides/
│   └── example.md # Expected: http://localhost:4321/guides/example
├── reference/
│   ├── example.md # Expected: http://localhost:4321/reference/example
│   └── index.md   # Expected: http://localhost:4321/reference/
└── index.mdx      # Expected: http://localhost:4321/

Case 1: One `pageFolders` entry and global `i18n` configuration with default content in the root

Configuration:

"frontMatter.preview.trailingSlash": true,
"frontMatter.content.i18n": [
  { "title": "English", "locale": "en", "path": "." },
  { "title": "Polish", "locale": "pl", "path": "pl" }
],
"frontMatter.content.pageFolders": [
  {
    "title": "Docs",
    "path": "[[workspace]]/src/content/docs/",
    "defaultLocale": "en",
    "previewPath": "/{{locale}}/{{pathToken.relPath}}/"
  }
],

Dashboard

With this setup, all seven pages are visible in the dashboard, but only index.mdx and pl/index.mdx have properly assigned locale. Other pages are listed without detected locale.

Preview paths

.
├── pl/ # locale
│   ├── reference/
│   │   ├── example.md # Received: ✅ http://localhost:4321/pl/reference/example/
│   │   └── index.md   # Received: ✅ http://localhost:4321/pl/reference/
│   └── index.mdx      # Received: ✅ http://localhost:4321/pl/
├── guides/
│   └── example.md # Received: ❌ http://localhost:4321/en/guides/example/
├── reference/
│   ├── example.md # Received: ❌ http://localhost:4321/en/reference/example/
│   └── index.md   # Received: ❌ http://localhost:4321/en/reference/
└── index.mdx      # Received: ❌ http://localhost:4321/en/docs/   💬 Here, the root folder name leaked into the preview path

Here, I think, users might expect to have one source of truth. The global i18n configuration. If path is set to "path": ".", it should be enough to generate correct preview path for setups with default content in the root.

Unless, there are some use cases for such granularity?

Case 2: Tweaked `previewPath` to include `|ignore:en` as described in the docs

Configuration:

"frontMatter.preview.trailingSlash": true,
"frontMatter.content.i18n": [
  { "title": "English", "locale": "en", "path": "." },
  { "title": "Polish", "locale": "pl", "path": "pl" }
],
"frontMatter.content.pageFolders": [
  {
    "title": "Docs",
    "path": "[[workspace]]/src/content/docs/",
    "defaultLocale": "en",
    "previewPath": "/{{locale|ignore:en}}/{{pathToken.relPath}}/"
  }
],

Dashboard

Pages in the dashboard are displayed in the same way as in Case 1.

Preview paths

.
├── pl/ # locale
│   ├── reference/
│   │   ├── example.md # Received: ✅ http://localhost:4321/pl/reference/example/
│   │   └── index.md   # Received: ✅ http://localhost:4321/pl/reference/
│   └── index.mdx      # Received: ✅ http://localhost:4321/pl/
├── guides/
│   └── example.md # Received: ❌ http://localhost:4321//guides/example/   💬 double slashes
├── reference/
│   ├── example.md # Received: ❌ http://localhost:4321//reference/example/   💬 double slashes
│   └── index.md   # Received: ✅ http://localhost:4321/reference/
└── index.mdx      # Received: ❌ http://localhost:4321/docs/   💬 the root folder name leaked into the preview path

Locale is not parsed when `"defaultLocale"` config is missing.

https://beta.frontmatter.codes/docs/content-creation/placeholders#example-5-using-the-locale-placeholder

I would suggest to add the "defaultLocale": "en", to the examples in the documentation, because without it, {{locale}} doesn't seem to be parsed at all.

Received preview path for index.mdx: http://localhost:4321/{{locale|ignore:en}}/docs/.

Used configuration (I removed the "defaultLocale": "en",):

"frontMatter.preview.trailingSlash": true,
"frontMatter.content.i18n": [
  { "title": "English", "locale": "en", "path": "." },
  { "title": "Polish", "locale": "pl", "path": "pl" }
],
"frontMatter.content.pageFolders": [
  {
    "title": "Docs",
    "path": "[[workspace]]/src/content/docs/",
    "previewPath": "/{{locale|ignore:en}}/{{pathToken.relPath}}/"
  }
],

Hope it helps! Cheers 👋

Docs have been updated! Thanks for the suggestion.

I will have to verify both of your cases how we can support these.

@theinfinit implemented a change to fix the double slash issue and the root folder reference, which is mentioned in case 2. It will be released in the beta version.

About case 1, it is expected when you use {{locale}} always to include a locale in the URL, that is why I've added the ignore property.

estruyf / vscode-front-matter