Why should a page pathLocale be customizable

[Mister-Hope]

VuePress internally mark pages with locale object, and this is a core feature of i18n support. Any page inside a locale folder will be isolated with that locale.

Why should an user set _i18n.pathLocale in frontmatter to override the locale a page belongs to, e.g.: /zh/example.html to /en/ ?

[DreamOfIce]

Frontmatter _i18n is just an internal field and normally users do not need to know this.
It used only when call createPage() inside the plugin to pass some data to extendsPage and will be deleted at that time:

vuepress-plugin-i18n/src/node/lib/untranslated.ts

Lines 28 to 44 in fc9cfd9

	const pageOptions = {
	path: page.path.replace(options.baseLocalePath, prefix),
	content: page.content,
	frontmatter: {
	...page.frontmatter,
	_i18n: {
	pathLocale: prefix,
	untranslated: true,
	},
	} as PageFrontmatter<I18nPluginFrontmatter>,
	};
	pageOptions.frontmatter._i18n ||= {};
	if (page.filePathRelative) {
	pageOptions.frontmatter._i18n.filePathRelative = `${prefix.slice(1)}${
	page.filePathRelative
	}`;
	}

vuepress-plugin-i18n/src/node/lib/pageData.ts

Lines 15 to 24 in fc9cfd9

	const i18nFrontmatter = (page.frontmatter as I18nPluginFrontmatter)["_i18n"];
	if (i18nFrontmatter?.pathLocale) page.pathLocale = i18nFrontmatter.pathLocale;
	page.data.i18n ||= {
	pathLocale: page.pathLocale,
	sourceLink: page.path.replace(page.pathLocale, options.baseLocalePath),
	untranslated: i18nFrontmatter?.untranslated ?? false,
	};
	delete page.frontmatter["_i18n"];

[Mister-Hope]

Every page should have pathLocale, so the question is still there, why there is a frontmatter._i18n.pathLocale?

[Mister-Hope]

If users do not need to set this field, then we absolutely do not need this field. I think the thing you should explain is that why users should sometimes set this field?

[DreamOfIce]

The root cause is: for auto-filled (I can't find a better expr at the moment) untranslated pages, we can only set the filePathRelative in the extendsPage hook.
This also causes the pathLocale property to always be /, so we have to override it manually

[DreamOfIce]

Regarding why the filePathRelative must be written in extendsPage:
Because theme-hope will only add pages with a non-empty filePathRelative attribute to the sidebar using "structure" mode, but the non-existent filePathRelative will make the git plugin throw an error.

This is the only way I can think of at the moment, but if you have a better solution that would be great!

[Mister-Hope]

I think I got you, so when you createPage to add a page, the page will not get a correct pathLocale right?

[DreamOfIce]

Yes, when filePathRelative is empty, pathLocale is always /:
https://github.com/vuepress/vuepress-next/blob/d91996fd0864abd5029e4c4cff319db48be06b47/packages/core/src/page/inferPagePath.ts#L17-L22