Convert /web/api to Markdown (ja)

[queengooborg]

This PR converts the /web/api folder to Markdown for the Japanese locale. This only affects files that have no conversion issues.

[mfuji09]

@queengooborg
Did you confirm to do this convert to ja translator's community?

So far we have been converting to markdown with a little bit of checking for updates. The fact that an article was in HTML was a mark that it was unconfirmed.

If you are going to make major changes, I think you should first consult with the translator community. And I think we should follow the community conventions without immediate self-approval.

[queengooborg]

Hi @mfuji09!

I apologize if this project wasn't clarified well, especially for your locale, and for any of the troubles this causes with your workflow. There is currently a pinned tracking issue for the complete conversion of all localized content to Markdown to follow the recent conversion completion of the English locale -- see #7486. This project has become a high priority as (as Ruth has told me) the Markdown conversion is a blocker for many of Yari's planned updates. The reason I have self-merged these PRs (and right away) is because this conversion project had already been planned and completed upstream, leaving only the localized content to be done (of which had been discussed a long time ago for translations specifically).

Once again, I apologize if this has disturbed your locale's workflow -- I'm still new to the localization project specifically and am not familiar with how each locale handles their translations, so I'm just sticking to what I know to do for the projects I typically work on!

In regards to "confirming" an article, perhaps the l10n.sourceCommit frontmatter key would serve that purpose better? The lack of the key could be used as a way to determine if a document needs to be checked, and then it can be added in during the review process!

[mfuji09]

@queengooborg
In the past, the MDN admins would contact me or someone in the ja community before making any major changes.
Since this change was made without notice, my works in a week which was waiting for review was wasted.
It is starting to seem ridiculous to follow the workflow.

I suppose we could use the idea of checking the parity of the documents, but is there a way to actually check this at a glance? Or do we have to open each file one by one to check?

[queengooborg]

In the past, the MDN admins would contact me or someone in the ja community before making any major changes.

I guess that Schalk wasn't able to meet with you all yet and clarify the plans -- unfortunately he's down with COVID at the moment...

Tell you what: let me revert the commits made to convert the Japanese localizations to Markdown, and then instead submit pull requests to convert them per folder? That should help give you (and the rest of the ja team) some time to review and merge other PRs, and migrate to Markdown when you're ready!

is there a way to actually check this at a glance?

From what I've been told, there's a localization dashboard available at http://localhost:3000/en-US/_translations if you have a local copy of Yari running -- that should help indicate the staleness of a document!

In the end, the goal is to add the sourceCommit key to all of the documents, and then the dashboard (and Yari as a whole) could be updated to announce when a document's been updated upstream and the translations need to be updated. Otherwise, all we have to go on right now is the last modified date (which is not a great metric anyways).

[queengooborg]

Markdown conversion for ja has all been reverted now! I'll rerun the script and resubmit changes after all the other locales are finished!

[mfuji09]

@queengooborg
Okay!
I will notify the ja community about it, and will review as quickly. I will notify you when it was prepared.

I want to ask you a thing: can you document the usage of localization dashboard (including usage of "localhost:3000") and the parity key? People of the ja community wants to know which file should be updated, but no good way was found.
Once a way to checking files should be updated is available, there will be no obstacle to convert to markdown.

[queengooborg]

I'm not all too familiar with the dashboard (as I mentioned earlier, I'm still fairly new to MDN's localization project), but I'll do some research and find documentation or write some up when I'm able to!

People of the ja community wants to know which file should be updated, but no good way was found.

This applies to all the other locales from what I've heard. Right now, there's no good way to determine which files should be reviewed and updated first before others -- the only statistic everyone has to go on is the date of the last time the file was modified, or whether the file has been converted to Markdown.

That's what the sourceCommit key is intended to do: provide a useful metric that identifies what commit from the upstream mdn/content the translation is synced with. I have plans to incorporate the key into Yari so that translators can easily track which files need to be worked on before others!

[mfuji09]

@queengooborg
It has been ready to convert to md. Now the all PRs which had to be resolved are clear.

There is one concern. Unlike many other languages, Japanese does not place spaces between words. So some of sentences may be converted wrongly.
So, if you can, try to convert few documents first, checking the result, then applying the converter wider (by section).