Re: Merging en & ja jlreq glossary

[r12a]

I thought it would be easier to handle the remaining work related to this by opening an issue.

[r12a]

[my initial email]

We need to decide how to handle the glossary in the multilingual jlreq document (see https://w3c.github.io/jlreq/temporary_bilingual_devt/#appendix_7).

APPROACH 1

Currently, because the ordering is different in english and japanese, the two tables of terms have not been merged. If you filter the document for english only, the whole japanese term table is hidden, and vice versa.

There are two issues with this approach:

1. each of the 180 rows in each table has an id, so that you can link to the term definition from the main text, and in the old jlreq for a given term that id was the same, whether the table was the english one or the japanese one. Having the same id twice in the document causes validation errors and causes problems for linking, so for now i renamed all ids in the japanese table to start with "ja-".

2. if we continue to have separate tables with language-specific ids, we need to change all the links to the japanese term rows throughout the rest of the text. Given that there are around 180 terms, and many if not all are pointed to from the main text several times, this is a big job if we are to do it by hand. It's more complicated than global search & replace because we mustn't change the links to the english table.

APPROACH 2

An alternative approach, which still involves a fair amount of work, but maybe less, would be to merge the two tables. The downside of this approach would be that the rows in the table would be ordered by the english sort order, rather than the japanese (because english is the authoritative version of the doc). Is this an issue?

Also, the japanese table has a yomi column, whereas the english table has a romaji column. Should we keep both ?

We may be able to add some scripting, so that when a user chooses english or japanese then the order of the table is changed. (The default multilingual order would probably need to remain as english ordering.) It would involve a fair amount of processing – particularly if the aim including rearranging the columns, as well as the rows – i don't know whether it would result in a perceived delay in displaying the page.

[r12a]

Current situation is that if you are viewing the document in Japanese, clicking on those links has no effect (because the Japanese version of the glossary is hidden).

I understand that this was discussed during a FTF, and a decision was taken to leave the glossaries as they are (ie. separate).

Given the decision to maintain the separation, all the Japanese .termref a elements need to be changed to point to the Japanese glossary. (This is, as mentioned above, quite a big job.) Who will do that work?

[kidayasuo]

We'll discuss this again at the next F2F. If the work required to update the termref is larger than merging the tables it would make more sense to do the merge.

[r12a]

I created an illustration of what a merged glossary could look like in a temporary version of the doc at
https://w3c.github.io/jlreq/temp-glossary.html#appendix_7

All that's need to complete the merge is some cut and pasting of the remaining terms during some down time. (I was able to use a regular expression search & replace to create the new table, so it didn't take long. I think that finishing it off will take only a fraction of the time it would take to remap all the japanese links in the document that point to the glossary.)

At some point we can add some javascript to the first two columns to allow people to sort the table by one language or another.

I also combined the romaji and hiragana transliterations into a single "Transliteration" column. So there's no impact on the width of the table at all.

Note that the description column will hide one language or the other when a language is chosen for display, but the other information remains as is (which i think is useful).

What do you think? Should we press ahead?

[xfq]

What do you think? Should we press ahead?

Looks good to me. I created a PR to show what it's like (for all the rows in the table): #88

[kidayasuo]

At the meeting the group's concern was that the merge would create additional work to bring it back to the same level of customer quality as it is today for both languages. We are already learning the lesson by deciding to merge the document itself. Fixing errata has clear customer benefits but changing internal implementation of a stable document has a danger of destabilising it.

I agree it is much cleaner if the table is merged. I am in favour of doing this work but probably when we work on the next big revision of the document, when it would be in anyway destabilised.

[r12a]

@kidayasuo i'm not clear on the specific issue here. The proposed PR doesn't change any text. It just merges the languages in the same way as we did for the main body of the text (the only reason i didn't change these tables then was because i wanted to double-check the alternatives, and i didn't expect it to become such a big deal).

There are currently around 1,250 termref links in the document, half of which will need to be changed, because currently the links from Japanese text don't work if viewing in Japanese (they need to be pointed to the Japanese table). And i think the process of fixing will need to be done and checked carefully. I see a risk here for the document integrity during conversion, and for future maintenance (since there need to be different links for en and ja text). On the other hand, the proposed PR avoids the need for any of that.

[kidayasuo]

What I meant by implementation includes html / javascript, and the customer quality includes the order of columns and how it is sorted for each language. With that said I just wanted to relay our concerns. If you believe it is the best to do this on the second revision I have no objections.

[r12a]

Thanks for the clarification. I think we should proceed and merge Fuqiao's PR. I suggest we leave it a couple of days for any further comments (though no one seems to be objecting so far), and then merge the PR.

[kidayasuo]

👍