suggestion: merge parent metadata in `Document.findByURL`

[yin1999]

Background

We have just merged parent (en-US) documents' metadata into l10n docs in kumascript, while we did also use some metadata (other than title and slug) to create sth like Breadcrumb (using short-title metadata).

For the most of them, we could just use the one in parent (en-US) document. As short-title, just like what @jasonren0403 pointed out, the short-title in en-US is not used as a fallback in l10n docs (see mdn/translated-content#12729). I think it's a good idea to do the same merging as the kumascript does, it would be easier for l10n contributors to maintain documents.

Suggestion

But we are still handling the merging of metadata in some scattered places (that means in kumascript for now), so I'm wondering that could we do this in Document.findByURL, as we can use these fallback metadata transparently.

[hochan222]

@yin1999 Hello, there was a short-title issue in ko-locale recently. Thanks for making the issue first.

Depending on the https://github.com/mdn/translated-content/issues/7412 issue, the current Korean guide recommends using only title, slug, original_slug and l10n.*.

If it is as suggested, would it be safe to assume that the existing guide will be maintained in the future?

short-title tag history

• https://github.com/mdn/mdn/issues/284
• https://github.com/mdn/yari/pull/7825
• https://github.com/mdn/translated-content/pull/12745#issuecomment-1510634163
• https://github.com/mdn/yari/issues/8627

[yin1999]

Hi @hochan222, the short-title frontmatter is added in #7825. Actually, it is a good idea to landing this, as we may use this to resolve the problem metioned here.

would it be safe to assume that the existing guide will be maintained in the future?

IMO, the short-title can be used to help us avoid maintaining localization of item names in sidebars (as we seems to only use function or property's name in short-title). So this should be safe to keep the current recommends in guidelines. But I'm not really sure about other usages of it (except for the breadcrumbs).

Maybe @wbamberg could tell the details about short-title :)

[wbamberg]

The idea of short-title is that it's an alternative title that can be used in contexts where using the full title is inappropriate, generally because of the context where the short title appears (like a sidebar or breadcrumbs).

I think it's probably safest just to treat short-title as a localizable piece of metadata, like title, and therefore not to inherit it from en-US. Although in Web/API the value of short-title is always an identifier and isn't localizable, there's no guarantee that this will always be the case, and indeed it already isn't in at least one case: https://github.com/mdn/content/blob/23346b58b7ef97cc21f34cb38d23b23487a9d097/files/en-us/web/progressive_web_apps/reference/index.md?plain=1#L2-L3.

[yin1999]

Thanks for the clarification. Because the metadata used in the macro will still inherit from en-US (that is, the sidebar macros that have using short-title metadata will still use the short-title metadata in en-US when this key is not set in localized document), and more than 90% of the pages using short-title are property or function/method pages, I think we still need to make some updates: removing the inheritance of short-title, or making the breadcrumb would also use the short-title metadata inherited from en- US if not set in localized documents.

[caugner]

I understand the suggestion as consolidating how we merge the parent metadata for translated documents by de-duplicating what we currently do in multiple places into a single place, such as Document.findByURL.

This makes sense, but I have added the "on hold" label, because @fiji-flo plans to re-achitecture the yari build system, so we should avoid making significant changes to the build process except for low effort low risk changes. If this suggestion falls into this category, we can remove the "on hold" label.