search

w3c / wai-statements

Accessibility Statements
https://w3c.github.io/wai-statements/planning/statements/
31 stars 64 forks source link

Feature: Internationalisation #143

Closed basdebruin closed 3 years ago

basdebruin commented 3 years ago

Adding easy internationalisation

Fix for issue #114

The generator.html has been split into:

This has been done to aid translators as it should be much easier now to add new languages without having to change any of the html or javascript.

Documentation in README.md and script in generator.js has been updated to work with the new files.

What still needs to be done:

hidde commented 3 years ago

@basdebruin Hi Bas, the issue with the Expand/Collapse not translating is that the translation code that is in wai-website-theme's main.js does not exist in the main.js in this repository. I'm not sure, why this is the case, but a quick fix would be these two changes:

At the start of main.js, add: 

  var t = function(enstring) {
    if (translationStrings[enstring]) {
      return translationStrings[enstring];
    } else {
      return enstring;
    }
  }

(adds the t function that deals with translation)

Replace line 319 with:

      el.innerHTML = '<button class="expand button button-secondary button-small">+ ' + t('Expand All Sections') + '</button> <button class="collapse button button-secondary button-small">&minus; ' + t('Collapse All Sections') + '</button>';

(wraps the content of the expand/collapse all buttons in the t function)

I did this locally and it works (I cannot commit code in the AccessibilityNL org, so feel free to grab the changes)

nitedog commented 3 years ago

@SteveALee can you please look into the configuration of this repo, and why it is not using the latest main.js file?

basdebruin commented 3 years ago

@basdebruin Hi Bas, the issue with the Expand/Collapse not translating is that the translation code that is in wai-website-theme's main.js does not exist in the main.js in this repository. I'm not sure, why this is the case, but a quick fix would be these two changes: ...

I copied over the code and the translation of the component now works. However, a more permanent fix would be to extend/use the main.js file from the wai-website-theme repository.

SteveALee commented 3 years ago

@nitedog @basdebruin @hidde

That code only appears in the main site and not in any of the previews. I suspect it is just an oversight as the previews are relatively new. There's no obvious reason not to have the same behaviour with the previews.

I'll add it to the wiki page tracking work to be done to the site.

SteveALee commented 3 years ago

I take it back! GitHub search is broken. A grep + find shows it is in fact in most of the main.js files. So I'll explore a little further

SteveALee commented 3 years ago

It appears that this (and only this) resource has it's own main.js but all other use this one from the wai-website-theme.

I've not idea why - perhaps it added code - but better to add an extra file for that as will get out of date.

Here's the diff (RHS = your local version)

nitedog commented 3 years ago

It seems to me that the shared one is more refined than the local one. @hidde could you please take a closer look?

@basdebruin besides the expand/collapse buttons, are there any functions you are using from the local main.js that are not in the shared copy?

hidde commented 3 years ago

@nitedog @basdebruin @SteveALee Seems to me we can safely use the shared main.js. Bas, would you like to do this in your branch?

SteveALee commented 3 years ago

@hidde @nitedog @basdebruin agree. It seems changes are small improvement and bug fixes.

Would you like me to make the change on master? You can them merge into branches that require it.

hidde commented 3 years ago

@SteveALee Yes, even better!

hidde commented 3 years ago

@SteveALee @basdebruin I have removed this repository's main.js in its master branch and verified that we now default to the global main.js, which includes the translation functionality.

@basdebruin if you merge remote into your repository you should get this change too

basdebruin commented 3 years ago

The feature should now be finished and can be merged! 🎉 There was one more question from Eric about the metadata in the generator(.nl).md file: not all the metadata at the top of the file is relevant for translators and it may be better to move this to the generator_layout.html file. It regards the following bits of metadata:

contributors: ...
layout: default
github: ...
external_css: ...

I'm not sure if it's possible to move metadata to the layout file but it may be worth looking into! It would make the translation experience even more seamless.

shawna-slh commented 3 years ago

There was one more question from Eric about the metadata ...

contributors:

Actually, there were some misunderstandings and missing points in the metadata. For example, "contributors" is contributors to the specific translation, not the original resource. I suggested updates here: https://github.com/AccessibilityNL/wai-statements/pull/2/files

I agree some of the metadata translators don't need to touch, yet some they do. For example:

github: repository: w3c/wai-statements path: "generator.md" # Add the language shortcode to the middle of the filename, for example: generator.nl.md

Given that there are only a couple lines that don't need translator edit, I think it's probably not worth it to move those.

To help with translation, we could make a version that highlights what text to translate. For example: https://docs.google.com/document/d/1TyAUCLpg1bnv10o8KQvHxCool7dFX1-EcNuub0Ntk38/edit

(Also, I have on my wishlist that we have a simple form that translators fill out and it creates a new file in GitHub with all the meta data filled in! :-)

shawna-slh commented 3 years ago

Suggestions for the Read Me to integrate with WAI-site-wide translation and put that succinct info at the top (and move background and wai site internal stuff to the bottom):

https://github.com/AccessibilityNL/wai-statements/pull/3/files

shawna-slh commented 3 years ago

I think I've submitted all my comments. Did I miss anything that you specially wanted me to comment on?

I notice the preview doesn't have the nl translation at the top.

And the navigation is missing from https://deploy-preview-143--wai-statements.netlify.app/planning/statements/generator/nl#create [/me remembers that's they way it is for new resources]

Maybe that's just because of the way the preview is set up or the type of changes?

Especially if we don't see things as we want in the preview, we should plan to coordinate publication so Steve, Bas, and I are available to address any issues together.

Also, a question: This is only for the generator page itself -- e.g. https://www.w3.org/WAI/planning/statements/generator/#create And translators would translate the other pages of the resource separately -- like any other page. Correct?

/me notes that we need to make sure those other pages are updated for translation as well.

shawna-slh commented 3 years ago

@basdebruin You will also need to update https://raw.githubusercontent.com/AccessibilityNL/wai-statements/feature/easy-translation/generator.nl.md with the corrections and clarifications that I made to the English version metadata (e.g., contributors is the translators, not developers), footer, etc.

@nitedog I guess we should change the date in the footer, since you did actually make some content changes. Here's what I had before:

Date: Updated underlying code (not the content) @@ February 2021. First published November 2018.

and I guess it should be just:

Date: Updated @@ February 2021. First published November 2018.

(with @@ being the publication date)