From b7189b5b7c3aec588c69d8a100f5129f55367513 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Tue, 3 Oct 2023 02:13:45 +0200 Subject: [PATCH 01/10] Add resource on preparing a resource for translations --- content/technical-translation.md | 86 ++++++++++++++++++++++++++++++++ content/writing.md | 2 +- 2 files changed, 87 insertions(+), 1 deletion(-) create mode 100755 content/technical-translation.md diff --git a/content/technical-translation.md b/content/technical-translation.md new file mode 100755 index 0000000..d145356 --- /dev/null +++ b/content/technical-translation.md @@ -0,0 +1,86 @@ +--- +title: "Preparing a Resource for Translations" +permalink: /technical/translations/ +lang: en +doc-note-type: draft +github: + repository: w3c/wai-website-theme + path: content/technical-translation.md +--- + +{::nomarkdown} +{% include box.html type="start" title="Summary" class="" %} +{:/} + +Tasks needed to get a resource ready for translations. + +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +{% include toc.html %} + +## Frontmatter template + +{::nomarkdown} +{% include box.html type="start" title="Code" class="example" %} +{:/} + +```md +--- +# Translation instructions are after the "#" character in this first section. They are comments that do not show up in the web page. You do not need to translate the instructions after "#". +# In this first section, do not translate the words before a colon. For example, do not translate "title:". Do translate the text after "title:". + +title: My Example Document +nav_title: "Standards/Guidelines" +lang: en # Change "en" to the translated-language shortcode +last_updated: 2020-11-11 # Put the date of this translation YYYY-MM-DD (with month in the middle) + +# translators: # remove from the beginning of this line and the lines below: "# " (the hash sign and the space) +# - name: "Translator Name Here" # Add one -name: line for every translator +# - name: "Jan Doe" # Replace Jan Doe with translator name +# - name: "Jan Doe" # Replace Jan Doe with name, or delete this line if not multiple translators +# contributors: +# - name: "Jan Doe" # Replace Jan Doe with contributor name, or delete this line if none +# - name: "Jan Doe" # Replace Jan Doe with name, or delete this line if not multiple contributors + +github: + repository: w3c/wai-std-gl-overview + path: index.md # Add the language shortcode to the middle of the filename, for example: content/index.fr.md + +permalink: /standards-guidelines/ # Add the language shortcode to the end, with no / at the end. For example /standards-guidelines/fr +ref: /standards-guidelines/ # Do not change this + +# In the footer below: +# Do not change the dates +# Do not translate or change CHANGELOG or ACKNOWLEDGEMENTS. (if CHANGELOG or ACKNOWLEDGEMENTS) +# Translate the other words below, including "Date:" and "Editor:" (Else) +# Translate the Working Group name. Leave the Working Group acronym in English. +footer: > +

Date: Updated 13 March 2019.

+

Editor: Shawn Lawton Henry.

+

Developed with input from the Education and Outreach Working Group (EOWG).

+ +# Read Translations Notes for this resource at https://github.com/w3c/wai-std-gl-overview#readme +--- + +This is content for my **Example** Document. +``` + +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +### Frontmatter checklist + +- All required frontmatter lines for translation interoperability are present. See [Frontmatter guide](/writing/frontmatter/) (lines marked with 🌐) +- Add comments +- Adapt footer translation notes depending on content +- Add link to repository translations notes when existing. + +## Main content + +### Links checklist + +- When links go to WAI website, make sure permalink is used and not full URI. See [link markdown explanation in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) +- When the linked text is the exact same as the title of the page on the WAI website, make sure it uses double brackets. See [link markdown explanation in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) diff --git a/content/writing.md b/content/writing.md index 43844b4..712ea04 100755 --- a/content/writing.md +++ b/content/writing.md @@ -40,7 +40,7 @@ To create a new page in an existing repository: * [Design Components](/components/) has things like boxes, table options, and much more. * [Style Guide](https://www.w3.org/WAI/EO/wiki/Style) has punctuation, editorial style, etc. * Images are covered in two places: [Design Components, Images]( https://wai-website-theme.netlify.app/components/images/) and [Create and Edit Documents, Images](/writing/images/)
_{@@To Do: Figure out if these should separate, or be combined. If separate, make sure they appropriately point to each other.}_ -* Note that **links need to be done a specific way** for translations. See [link markdown explanation in the in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) +* Note that **links need to be done a specific way** for translations. See [link markdown explanation in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) ## Changelogs From 16b363194470df2e56cd6c8de67df2ef91513d29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Tue, 3 Oct 2023 15:31:58 +0200 Subject: [PATCH 02/10] Fix navigation --- content/technical-translation.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/technical-translation.md b/content/technical-translation.md index d145356..02bf42b 100755 --- a/content/technical-translation.md +++ b/content/technical-translation.md @@ -2,10 +2,10 @@ title: "Preparing a Resource for Translations" permalink: /technical/translations/ lang: en -doc-note-type: draft github: repository: w3c/wai-website-theme path: content/technical-translation.md +doc-note-type: draft --- {::nomarkdown} @@ -48,6 +48,10 @@ github: repository: w3c/wai-std-gl-overview path: index.md # Add the language shortcode to the middle of the filename, for example: content/index.fr.md +navigation: + previous: /path/to/previous/file/ + next: /path/to/next/file/ + permalink: /standards-guidelines/ # Add the language shortcode to the end, with no / at the end. For example /standards-guidelines/fr ref: /standards-guidelines/ # Do not change this From d51bd14cc9aff2adcfec040b285a54bca5a7bcea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Wed, 20 Dec 2023 14:43:25 +0100 Subject: [PATCH 03/10] Update video player component --- _components/video-player-data.md | 40 ++++++++++++++++++++++++++++++++ _components/video-player.md | 14 ++++------- _data/navigation.yml | 2 ++ _data/video-metadata.yml | 1 + wai-videos | 1 + 5 files changed, 48 insertions(+), 10 deletions(-) create mode 100644 _components/video-player-data.md create mode 120000 _data/video-metadata.yml create mode 120000 wai-videos diff --git a/_components/video-player-data.md b/_components/video-player-data.md new file mode 100644 index 0000000..5af7f62 --- /dev/null +++ b/_components/video-player-data.md @@ -0,0 +1,40 @@ +--- +title: "Video Player" +lang: en +inline_css: | +--- + +## Code + +Embedding the video player: + +```liquid +{%raw%}{% include video-player-data.html + video-id="video-introduction" + yt-id="20SHvU2PKsM" +%}{% endraw%} +``` + +### Parameters + +`yt-id="20SHvU2PKsM"` +`yt-id-ad="1rBwxGMT9ZM"` +: YouTube ID of the video, `-ad` for the audio described version + +`video-id="video-introduction"` +: Unique identifier of the video, as used in video-metadata.yml & VTT files basenames. + +## Behaviour + +- Based on video id, the video player component automatically uses all related VTT files. +- Captions/subtitles and descriptions in the language of the page are selected by default. +- The user can still select any other available language in the video player interface, to see the captions/subtitles/descriptions in another language. +- If the language of the page is supported by AblePlayer, the video player interface is displayed in that language. + +## Example + +{% include video-player-data.html + video-id="video-introduction" + yt-id="20SHvU2PKsM" +%} + diff --git a/_components/video-player.md b/_components/video-player.md index 488ee87..6f64d7b 100644 --- a/_components/video-player.md +++ b/_components/video-player.md @@ -1,14 +1,8 @@ --- -title: "Video Player" +title: "Video Player (deprecated version)" lang: en -# translators: # Uncomment (remove #) for translations, one - name line per translator. -# - name: Translator 1 -# - name: Translator 2 -# contributors: -# - name: Contributor 1 -# - name: Contributor 2 -footer: > # Text in footer in HTML -

This is the text in the footer

+doc-note-type: deprecated +doc-note-message-md: The template is deprecated. inline_css: | --- @@ -60,4 +54,4 @@ It is possible to concatenate multiple sets of those subtitles using commas. See {% include video-player.html yt-id="20SHvU2PKsM" - %} \ No newline at end of file + %} diff --git a/_data/navigation.yml b/_data/navigation.yml index 77d5fba..f4f28be 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -131,6 +131,8 @@ - name: "Video Links" url: "/components/video-links/" - name: "Video Player" + url: "/components/video-player-data/" + - name: "Video Player (deprecated)" url: "/components/video-player/" - name: "Your Report" url: "/components/your-report/" diff --git a/_data/video-metadata.yml b/_data/video-metadata.yml new file mode 120000 index 0000000..efd87c9 --- /dev/null +++ b/_data/video-metadata.yml @@ -0,0 +1 @@ +../_external/data/video-metadata.yml \ No newline at end of file diff --git a/wai-videos b/wai-videos new file mode 120000 index 0000000..c56a36e --- /dev/null +++ b/wai-videos @@ -0,0 +1 @@ +_external/data/wai-videos/ \ No newline at end of file From 0b59edebbcc56bc66309c26b1a8a27f2a96f5297 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Wed, 20 Dec 2023 16:39:12 +0100 Subject: [PATCH 04/10] Add new Videos page --- _data/navigation.yml | 2 + content/writing-videos.md | 156 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) create mode 100755 content/writing-videos.md diff --git a/_data/navigation.yml b/_data/navigation.yml index f4f28be..44a8373 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -32,6 +32,8 @@ url: "/writing/html/" - name: Images url: "/writing/images/" + - name: Videos + url: "/writing/videos/" - name: Stand-alone Resources url: "/writing/standalone-resources/" - name: diff --git a/content/writing-videos.md b/content/writing-videos.md new file mode 100755 index 0000000..ed29a0d --- /dev/null +++ b/content/writing-videos.md @@ -0,0 +1,156 @@ +--- +title: "Videos" +permalink: /writing/videos/ +ref: /writing/videos/ +lang: en +github: + repository: w3c/wai-website-theme + path: content/writing-videos.md +--- + +{::nomarkdown} +{% include box.html type="start" title="Summary" class="" %} +{:/} + +This section covers the steps to correctly integrate a YouTube video into the wai-website. + +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +{% include toc.html %} + +## Step 1: Publish the video on YouTube (preferred) + +The [video player component](/components/video-player-data/) is currently designed for videos hosted on YouTube. + +## Step 2: Update the _video-metadata.yml_ file to include the new video + +The _video-metadata.yml_ file contains all videos captions, subtitles and descriptions metadata. It is centrally edited in the [wai-website-data {% include_cached external.html %}](https://github.com/w3c/wai-website-data) repository. + +Each entry for a video looks like this: + +{::nomarkdown} +{% include box.html type="start" title="Example" %} +{:/} +```yaml +- id: keyboard + name: + en: "Web Accessibility Perspectives: Keyboard Compatibility" + main-page: /perspective-videos/keyboard/ + path: perspective-videos + lang-folder: true + captions: + - en + subtitles: + - fr + descriptions: + - en + captions-ad: + - en + subtitles-ad: + - fr + descriptions-ad: + - en +``` +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +### Add an entry for the new video. + +{::nomarkdown} +{% include box.html type="start" class="simple" %} +{:/} + +In the following list, parameters are highlighted with emoji: +- ❗ = required for the _video-player-data_ component +- 🌐 = required for translation interoperability/functionalities + +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +- `id` β—πŸŒ\ +A short unique name that describes the video. Will be used as video identifier. + +- `name` 🌐\ +A title that describes the video. Will be used in [All WAI Translations Page](https://www.w3.org/WAI/translations/) when video subtitles in other languages are published. + +- `main-page` 🌐\ +[`ref` value](/writing/frontmatter/#ref) of the main page displaying the video; preferably a page with most accessibility features. Will be used in [All WAI Translations Page](https://www.w3.org/WAI/translations/). + +- `path` β—πŸŒ\ +From "wai-videos" folder, path to the VTT files for this video. + +- `lang-folder` (optional)\ +When present and set to `true`, means VTT files for a language are located in a subfolder named after the language shortcode. Example: `perspective-videos/en` rather than directly in `perspective-videos/`. + +- `captions`β—πŸŒ\ +Captions' language subtag. Usually `en`. + +- `descriptions`\ +List of language subtags of the available descriptions. + +- `captions-ad`\ +Captions' language of the described video (when existing). Usually `en`. + +- `descriptions-ad`\ +List of language subtags of the available descriptions, for the described video (when existing). + +The following parameters are not necessary for a new video, but should be added when the video captions are translated in other languages: + +- `subtitles` 🌐\ + List of language subtags of the available subtitles. + +- `subtitles-ad` \ + List of language subtags of the available subtitles, for the described video (when existing). + +## Add VTT files in _wai-website-data_ repository + +All VTT files are stored in `wai-website-data` repository, in `wai-videos` folder. + +Inside this folder, VTT files can be organized in subfolders. + +{::nomarkdown} +{% include box.html type="start" title="Directory structure illustration" %} +{:/} +``` +. +β”œβ”€β”€ wai-videos +β”‚ β”œβ”€β”€ perspective-videos +β”‚ β”‚ β”œβ”€β”€ en +β”‚ β”‚ β”‚ β”œβ”€β”€ keyboard.en.vtt +β”‚ β”‚ β”‚ β”œβ”€β”€ keyboard_ad.en.vtt +β”‚ β”‚ β”‚ β”œβ”€β”€ keyboard_ad_desc.en.vtt +β”‚ β”‚ β”‚ └── captions.en.vtt +β”‚ β”‚ └── fr +β”‚ β”‚ β”œβ”€β”€ keyboard.fr.vtt +β”‚ β”‚ β”œβ”€β”€ keyboard_ad.fr.vtt +β”‚ β”‚ β”œβ”€β”€ keyboard_ad_desc.fr.vtt +β”‚ β”‚ └── captions.fr.vtt +β”‚ └── video-introduction +β”‚ β”œβ”€β”€ video-introduction.en.vtt +β”‚ β”œβ”€β”€ video-introduction.fr.vtt +β”‚ β”œβ”€β”€ video-introduction.de.vtt +β”‚ └── video-introduction.zh-hans.vtt +└── ... +``` +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +VTT filenames must follow the following convention: +- Captions/Subtitles: ``.``.vtt +- Captions/Subtitles (described video): `_ad`.``.vtt +- Descriptions: `_desc`.``.vtt +- Descriptions (described video): `_ad_desc`.``.vtt + +## Step 3: Embed the video in a resource + +The description on how to embed videos is available on the [Video Player Design Component Page](/components/video-player-data/). + +## Translations + +Guidance on how to translate videos captions/subtitles/descriptions is available in the [Translating Video Subtitles and Descriptions Guide](https://www.w3.org/WAI/about/translating/guides/video-subtitles/) + From 5d0083f72efdfa29783308d87a37ce8caf8c99f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Wed, 20 Dec 2023 17:43:56 +0100 Subject: [PATCH 05/10] Update Translations documentation --- _data/navigation.yml | 2 + content/technical-translation.md | 140 ++++++++++++++++++++++++++++--- 2 files changed, 131 insertions(+), 11 deletions(-) diff --git a/_data/navigation.yml b/_data/navigation.yml index 44a8373..cacbca3 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -17,6 +17,8 @@ url: "/technical/integrating-resource/" - name: Navigation url: "/technical/navigation/" + - name: Translations + url: "/technical/translations/" - name: en: 'Create and Edit Documents' pages: diff --git a/content/technical-translation.md b/content/technical-translation.md index 02bf42b..3589ce5 100755 --- a/content/technical-translation.md +++ b/content/technical-translation.md @@ -1,18 +1,18 @@ --- -title: "Preparing a Resource for Translations" +title: "Translations" permalink: /technical/translations/ +ref: /technical/translations/ lang: en github: repository: w3c/wai-website-theme path: content/technical-translation.md -doc-note-type: draft --- {::nomarkdown} {% include box.html type="start" title="Summary" class="" %} {:/} -Tasks needed to get a resource ready for translations. +Documentation related to WAI website translations. {::nomarkdown} {% include box.html type="end" %} @@ -20,13 +20,18 @@ Tasks needed to get a resource ready for translations. {% include toc.html %} -## Frontmatter template +## Prepare a Resource for Translations {::nomarkdown} -{% include box.html type="start" title="Code" class="example" %} +{% include box.html type="start" title="Frontmatter Template" class="example" %} {:/} +{% include excol.html type="start" id="optional-id" %} -```md +Show template + +{% include excol.html type="middle" %} + +```yml --- # Translation instructions are after the "#" character in this first section. They are comments that do not show up in the web page. You do not need to translate the instructions after "#". # In this first section, do not translate the words before a colon. For example, do not translate "title:". Do translate the text after "title:". @@ -71,6 +76,7 @@ footer: > This is content for my **Example** Document. ``` +{% include excol.html type="end" %} {::nomarkdown} {% include box.html type="end" %} {:/} @@ -78,13 +84,125 @@ This is content for my **Example** Document. ### Frontmatter checklist - All required frontmatter lines for translation interoperability are present. See [Frontmatter guide](/writing/frontmatter/) (lines marked with 🌐) -- Add comments -- Adapt footer translation notes depending on content -- Add link to repository translations notes when existing. +- Add translation instructions comments when missing +- Adapt footer translation instructions depending on content (changelog, acknowledgements, etc.) +- Add a link to the repository `Readme` file when it contains resource-specific Translations Notes. -## Main content +### Main content -### Links checklist +#### Links checklist - When links go to WAI website, make sure permalink is used and not full URI. See [link markdown explanation in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) - When the linked text is the exact same as the title of the page on the WAI website, make sure it uses double brackets. See [link markdown explanation in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) + +## Update Translations Priorities + +Priorities for Translating WAI Resources are listed in the [Step-by-Step Guide to Translating WAI Resources](https://www.w3.org/WAI/about/translating/step-by-step/#priorities) and in Translations Sitemaps. + +To update the priorities list: +1. Navigate to the [wai-website-data {% include_cached external.html %}](https://github.com/w3c/wai-website-data) repository. +2. Update the `translations-priorities.yml` file as follows: +- `url`: [`ref` value](/writing/frontmatter/#ref) of the resource. +- Arrange lines in the order you want them to appear in the priorities list. +- If you want resource subpages to be displayed, use `pages:` and list subpages `url`s below. + +{::nomarkdown} +{% include box.html type="start" title="Example" %} +{:/} +```yaml +- url: "/videos/standards-and-benefits/" +- url: "/fundamentals/accessibility-intro/" +- url: "/tips/" + pages: + - url: "/tips/writing/" + - url: "/tips/designing/" + - url: "/tips/developing/" +``` +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +## Add Translations Sitemaps + +New Translations Sitemaps can easily be created. + +To add a new translation sitemap: +1. Navigate to the [wai-about-wai {% include_cached external.html %}](https://github.com/w3c/wai-about-wai) repository. +2. In the `_about/translating/sitemaps/` folder, duplicate an existing sitemap. +3. Name the new file as follows: `sitemap-.md` +4. Update the following frontmatter parameters: + - `title`\ + Update language name. Example: "Spanish Translations Progress" + - `nav_title`\ + Update language name. Example: "Spanish" + - `github` > `path`\ + Update filename. Example: `_about/sitemaps/sitemap-es.md` + - `permalink`\ + Update with language subtag. Example: `/about/translating/sitemaps/sitemap-es/` + - `ref`\ + Update with language subtag. Example: `/about/translating/sitemaps/sitemap-es/` + - `tlang`\ + Update with language subtag. + - **Note: Do not update `lang` parameter (the language used in the page is English).** +5. Add this new page in `navigation.yml`, in [wai-website-data {% include_cached external.html %}](https://github.com/w3c/wai-website-data) repository. +6. When published, [Translations Sitemaps list](https://www.w3.org/WAI/about/translating/sitemaps/) will automatically be updated. + +## Manually Add Translations in "All WAI Translations page" + +Some stand-alone resources are not automatically listed in [All WAI Translations page](https://www.w3.org/WAI/translations/). + +To manually add resources translations: +1. Navigate to the [wai-website {% include_cached external.html %}](https://github.com/w3c/wai-website) repository. +2. Update the `translations.md` frontmatter as follows: + +{::nomarkdown} +{% include box.html type="start" title="Note" %} +{:/} + +In the following list, parameters with ❗ emoji are required. + +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +- `lang` ❗\ + Language subtag. + +- `title` ❗\ + Translated resource title. + +- `en_title` ❗\ + Original resource title. + +- `url` ❗\ + Absolute link to the resource. + +- `translators` \ + Every translator is specified by their name in a separate line. In addition, organization name can be added (note: see [names and links policy](https://www.w3.org/WAI/about/translating/#links)) + +- `contributors` \ + Every contributor is specified by their name in a separate line. In addition, organization name can be added (note: see [names and links policy](https://www.w3.org/WAI/about/translating/#links)) + + +{::nomarkdown} +{% include box.html type="start" title="Example" %} +{:/} +```yaml +other_resources: + - lang: "fr" + docs: + - title: "Outil de rapport WCAG-EM" + en_title: "WCAG-EM Report Tool" + url: https://www.w3.org/WAI/eval/report-tool/ + translators: + - name: "Jane Doe" + org: "Example Organization" + contributors: + - name: "John Doe" + org: "Example Organization" +``` +{::nomarkdown} +{% include box.html type="end" %} +{:/} + + From 6e3603e5d43b1d1fac6aaebc8acd8fe3053ef9d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Wed, 20 Dec 2023 17:48:32 +0100 Subject: [PATCH 06/10] Update manually add translations --- content/technical-translation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/technical-translation.md b/content/technical-translation.md index 3589ce5..dccc941 100755 --- a/content/technical-translation.md +++ b/content/technical-translation.md @@ -153,7 +153,7 @@ Some stand-alone resources are not automatically listed in [All WAI Translations To manually add resources translations: 1. Navigate to the [wai-website {% include_cached external.html %}](https://github.com/w3c/wai-website) repository. -2. Update the `translations.md` frontmatter as follows: +2. In `translations.md` frontmatter, update `other_resources` metadata as follows: {::nomarkdown} {% include box.html type="start" title="Note" %} From 6efabeebacb3b269762e85d207fc7f1236da10b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Wed, 20 Dec 2023 19:49:14 +0100 Subject: [PATCH 07/10] Add technical details --- content/technical-translation.md | 50 ++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/content/technical-translation.md b/content/technical-translation.md index dccc941..16d073d 100755 --- a/content/technical-translation.md +++ b/content/technical-translation.md @@ -205,4 +205,54 @@ other_resources: {% include box.html type="end" %} {:/} +## Technical Details + +### Translated pages in header + +When a page has been translated into one or more languages, links to these translations are displayed at the top of the page. +This part is managed by [_includes/header.html](https://github.com/w3c/wai-website-theme/blob/master/_includes/header.html) + +{::nomarkdown} +{% include box.html type="start" title="Example" %} +{:/} +
+This page in: + +
+{::nomarkdown} +{% include box.html type="end" %} +{:/} + +Features: +- The section lists Jekyll pages with the same [`ref`](/writing/frontmatter/#ref). \ +**Note:** If multiple pages are found with the same [`lang`](/writing/frontmatter/#lang), this section will not work well. +- Language names displayed come from [`lang.json` file {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/lang.json) (`nativeName` value, capitalized using inline CSS). +- `dir` attribute is set to `auto` (see [associated behaviour in this W3C Internationalization page {% include_cached external.html %}](https://www.w3.org/International/questions/qa-html-dir#dirauto)) +- `hreflang` attribute is missing (TO DO) +- If "This page in:" has been translated into the language of the current page (in [`translations.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/translations.yml)), this translation is used. + +### Links to other pages + +[WAI Markdown Extension](/writing/wai-markdown/) automatically modifies links to WAI website internal links, based on the following rules. + +The extension looks for a translated version of the linked-to page: that is, a page sharing the same [`lang`](/writing/frontmatter/#lang) as the current page, and the same [`ref`](/writing/frontmatter/#ref) as the linked-to page: +- When a translation is found, the links points to the translated page. +- When no translation is found: + - The links points to the English version; + - "(in English)" is added at the end of the link, in the language of the page (if translated in [`translations.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/translations.yml)) + +Link text is defined as follows: +- When single-brackets are used: \ +Example: `[Custom link text]({%raw%}/{%endraw%}path/to/filename/)` + - The custom link text defined between the brackets is used. + +- When double-brackets are used:\ +Example: `[[Title of WAI Page]]({%raw%}/{%endraw%}path/to/filename/)` + - The [title](/writing/frontmatter/#title) of the linked-to page is used as link text.\ + This is the title of the translated page if a translation has been found; the title of the English version otherwise. + - The link text between brackets is ignored. From 206bb01aaf746a532c0b816a3ba592d4f00ff3e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Wed, 20 Dec 2023 19:51:58 +0100 Subject: [PATCH 08/10] Add hreflang detail --- content/technical-translation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/technical-translation.md b/content/technical-translation.md index 16d073d..f0a3ae8 100755 --- a/content/technical-translation.md +++ b/content/technical-translation.md @@ -243,6 +243,7 @@ The extension looks for a translated version of the linked-to page: that is, a p - When a translation is found, the links points to the translated page. - When no translation is found: - The links points to the English version; + - `hreflang` attribute is set to `en`; - "(in English)" is added at the end of the link, in the language of the page (if translated in [`translations.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/translations.yml)) Link text is defined as follows: From 5e79b0ded4fafd0dd3a79243d86a01d79c066aaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Thu, 21 Dec 2023 11:49:37 +0100 Subject: [PATCH 09/10] Add new documentatioon --- content/technical-translation.md | 150 ++++++++++++++++++++++++++++++- 1 file changed, 146 insertions(+), 4 deletions(-) diff --git a/content/technical-translation.md b/content/technical-translation.md index f0a3ae8..98a478a 100755 --- a/content/technical-translation.md +++ b/content/technical-translation.md @@ -147,7 +147,66 @@ To add a new translation sitemap: 5. Add this new page in `navigation.yml`, in [wai-website-data {% include_cached external.html %}](https://github.com/w3c/wai-website-data) repository. 6. When published, [Translations Sitemaps list](https://www.w3.org/WAI/about/translating/sitemaps/) will automatically be updated. -## Manually Add Translations in "All WAI Translations page" + +## "All WAI Translations" Page + +This page lists translations of the following items: +- resources on WAI website (automatic) +- video captions/subtitles/descriptions (automatic) +- accessibility standards (manual) +- stand-alone resources such as WCAG-EM Report Tool (manual) + +Logic is directly coded in [`translations.md` {% include_cached external.html %}](https://github.com/w3c/wai-website/blob/master/translations.md). + +### WAI Website Resources + +Most translations hosted on WAI website are automatically listed. + +**If a translation is not shown**, check the presence of the following parameters in the resource frontmatter: +- [`lang`](/writing/frontmatter/#lang) +- [`ref`](/writing/frontmatter/#ref) +- [`title`](/writing/frontmatter/#title) + +**To group parts of a multi-page resource in the list**: + +{::nomarkdown} +
    +
  1. +{:/} +In the main page of the resource, add and adapt the following parameters in the frontmatter: + +{::nomarkdown} +{% include box.html type="start" class="simple" %} +{:/} +```yaml +resource: + title: "How People with Disabilities Use the Web" + ref: /people-use-web/ +``` +{::nomarkdown} +{% include box.html type="end" %} +
    2. +
  2. +{:/} + +In other resource pages, add the main page `ref` in the frontmatter: + +{::nomarkdown} +{% include box.html type="start" class="simple" %} +{:/} + +```yaml +resource: + ref: /people-use-web/ +``` + +{::nomarkdown} +{% include box.html type="end" %} +
    3. +
+{:/} + +### Manually Added Translations Some stand-alone resources are not automatically listed in [All WAI Translations page](https://www.w3.org/WAI/translations/). @@ -159,7 +218,9 @@ To manually add resources translations: {% include box.html type="start" title="Note" %} {:/} -In the following list, parameters with ❗ emoji are required. +In the following list, parameters are highlighted with emoji: +- ❗ = required +- 🌐 = required for translation {::nomarkdown} {% include box.html type="end" %} @@ -168,7 +229,7 @@ In the following list, parameters with ❗ emoji are required. - `lang` ❗\ Language subtag. -- `title` ❗\ +- `title` 🌐\ Translated resource title. - `en_title` ❗\ @@ -187,6 +248,12 @@ In the following list, parameters with ❗ emoji are required. {::nomarkdown} {% include box.html type="start" title="Example" %} {:/} +{% include excol.html type="start" id="optional-id" %} + +Show example + +{% include excol.html type="middle" %} + ```yaml other_resources: - lang: "fr" @@ -201,13 +268,88 @@ other_resources: - name: "John Doe" org: "Example Organization" ``` +{% include excol.html type="end" %} +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +### Video Subtitles + +Information is pulled from [`video-metadata.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/video-metadata.yml) file, in particular: +- `name`: video translated title and English title. +- `main-page`: URL of the main page where the video is shown. + +Notes: +- Translators are not displayed (TO DO) +- "Video Subtitles" heading can be translated when it is added in [`translations.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/translations.yml). (TO DO) + +### Accessibility Standards Translations + +Accessibility standards translations must be manually listed. + +To manually add accessibility standards translations: +1. Navigate to the [wai-website {% include_cached external.html %}](https://github.com/w3c/wai-website) repository. +2. In `translations.md` frontmatter, update `translated_standards` metadata as follows: + +{::nomarkdown} +{% include box.html type="start" title="Note" %} +{:/} + +In the following list, parameters are highlighted with emoji: +- ❗ = required +- 🌐 = required for translation + +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +- `lang` ❗\ + Language subtag. + +- `title` 🌐 \ + Translated resource title. + +- `en_title` ❗\ + Original resource title. + +- `url` ❗\ + Absolute link to the resource. + +- `type` \ + - `authorized` when Authorized Translation + - `external` when Unofficial Translation + +- `translator` \ + Name of the lead translating organization/individual. + +{::nomarkdown} +{% include box.html type="start" title="Example" %} +{:/} +{% include excol.html type="start" id="optional-id" %} + +Show example + +{% include excol.html type="middle" %} + +```yaml +translated_standards: + - lang: "it" + docs: + - title: "Linee guida per l'accessibilitΓ  dei contenuti Web (WCAG) 2.2" + en_title: "Web Content Accessibility Guidelines (WCAG) 2.2" + url: https://www.w3.org/Translations/WCAG22-it/ + type: authorized + translator: "International Web Association" +``` +{% include excol.html type="end" %} {::nomarkdown} {% include box.html type="end" %} {:/} + ## Technical Details -### Translated pages in header +### Translated Pages in Header When a page has been translated into one or more languages, links to these translations are displayed at the top of the page. This part is managed by [_includes/header.html](https://github.com/w3c/wai-website-theme/blob/master/_includes/header.html) From 4d92506d7cbbcfcddd36b5e1d74e879c7c356002 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Re=CC=81mi=20Be=CC=81tin?= Date: Thu, 21 Dec 2023 12:24:11 +0100 Subject: [PATCH 10/10] Update documentation --- content/technical-translation.md | 67 +++++++++++++++++--------------- 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/content/technical-translation.md b/content/technical-translation.md index 98a478a..1deb69c 100755 --- a/content/technical-translation.md +++ b/content/technical-translation.md @@ -81,19 +81,25 @@ This is content for my **Example** Document. {% include box.html type="end" %} {:/} -### Frontmatter checklist +### Frontmatter Checklist -- All required frontmatter lines for translation interoperability are present. See [Frontmatter guide](/writing/frontmatter/) (lines marked with 🌐) +- Check that all the frontmatter lines that are required for translation interoperability are present. See [Frontmatter guide](/writing/frontmatter/) (lines marked with 🌐) - Add translation instructions comments when missing - Adapt footer translation instructions depending on content (changelog, acknowledgements, etc.) -- Add a link to the repository `Readme` file when it contains resource-specific Translations Notes. +- If specific instructions must be followed to translate this resoruce, add a link to the repository `Readme` file containing the Translations Notes. -### Main content +### Markdown Links Checklist -#### Links checklist +- When using internal links on WAI website, make sure the [`permalink`](/writing/frontmatter/#permalink) is used and not the full URI.\ + Good example: `[More on Planning](/media/av/planning/)`\ + Bad example: `[More on Planning](https://www.w3.org/WAI/media/av/planning/#wcag-standard)`. +- When the linked text is the exact same as the title of the page on the WAI website, make sure it uses double brackets.\ +Good Example: `[[Planning Audio and Video Media]]({%raw%}/{%endraw%}media/av/planning/)`\ +Bad example: `[Planning Audio and Video Media]({%raw%}/{%endraw%}media/av/planning/)` -- When links go to WAI website, make sure permalink is used and not full URI. See [link markdown explanation in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) -- When the linked text is the exact same as the title of the page on the WAI website, make sure it uses double brackets. See [link markdown explanation in the template](https://github.com/w3c/wai-resource-template/blob/master/content/index.md#heading-level-2) +- When the link goes to a fragment of a WAI website page, make sure the fragment is preceded by a slash.\ +Good example: `[WCAG](/media/av/planning/#wcag-standard)`\ +Bad example: `[WCAG](/media/av/planning#wcag-standard)`. ## Update Translations Priorities @@ -102,9 +108,9 @@ Priorities for Translating WAI Resources are listed in the [Step-by-Step Guide t To update the priorities list: 1. Navigate to the [wai-website-data {% include_cached external.html %}](https://github.com/w3c/wai-website-data) repository. 2. Update the `translations-priorities.yml` file as follows: -- `url`: [`ref` value](/writing/frontmatter/#ref) of the resource. +- `url` = [`ref`](/writing/frontmatter/#ref) of the resource. - Arrange lines in the order you want them to appear in the priorities list. -- If you want resource subpages to be displayed, use `pages:` and list subpages `url`s below. +- If you want the subpages of a resource to be displayed, list their `url`s in a `pages` section. {::nomarkdown} {% include box.html type="start" title="Example" %} @@ -138,13 +144,13 @@ To add a new translation sitemap: - `github` > `path`\ Update filename. Example: `_about/sitemaps/sitemap-es.md` - `permalink`\ - Update with language subtag. Example: `/about/translating/sitemaps/sitemap-es/` + Update language subtag. Example: `/about/translating/sitemaps/sitemap-es/` - `ref`\ - Update with language subtag. Example: `/about/translating/sitemaps/sitemap-es/` + Update language subtag. Example: `/about/translating/sitemaps/sitemap-es/` - `tlang`\ - Update with language subtag. - - **Note: Do not update `lang` parameter (the language used in the page is English).** -5. Add this new page in `navigation.yml`, in [wai-website-data {% include_cached external.html %}](https://github.com/w3c/wai-website-data) repository. + Update language subtag. + - **Note: Do not update `lang` parameter (the language used in the page is still English).** +5. For the new page to appear in the secondary menu, add this new page in `navigation.yml`, in [wai-website-data {% include_cached external.html %}](https://github.com/w3c/wai-website-data) repository. 6. When published, [Translations Sitemaps list](https://www.w3.org/WAI/about/translating/sitemaps/) will automatically be updated. @@ -152,9 +158,9 @@ To add a new translation sitemap: This page lists translations of the following items: - resources on WAI website (automatic) -- video captions/subtitles/descriptions (automatic) +- video subtitles (automatic) - accessibility standards (manual) -- stand-alone resources such as WCAG-EM Report Tool (manual) +- stand-alone resources such as the WCAG-EM Report Tool (manual) Logic is directly coded in [`translations.md` {% include_cached external.html %}](https://github.com/w3c/wai-website/blob/master/translations.md). @@ -210,7 +216,7 @@ resource: Some stand-alone resources are not automatically listed in [All WAI Translations page](https://www.w3.org/WAI/translations/). -To manually add resources translations: +To manually add those translations to the list: 1. Navigate to the [wai-website {% include_cached external.html %}](https://github.com/w3c/wai-website) repository. 2. In `translations.md` frontmatter, update `other_resources` metadata as follows: @@ -273,16 +279,6 @@ other_resources: {% include box.html type="end" %} {:/} -### Video Subtitles - -Information is pulled from [`video-metadata.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/video-metadata.yml) file, in particular: -- `name`: video translated title and English title. -- `main-page`: URL of the main page where the video is shown. - -Notes: -- Translators are not displayed (TO DO) -- "Video Subtitles" heading can be translated when it is added in [`translations.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/translations.yml). (TO DO) - ### Accessibility Standards Translations Accessibility standards translations must be manually listed. @@ -346,6 +342,15 @@ translated_standards: {% include box.html type="end" %} {:/} +### Video Subtitles + +Information is pulled from [`video-metadata.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/video-metadata.yml) file. This includes in particular: +- `name`: translated title of the video, and English title. +- `main-page`: URL of the main page where the video is shown. + +Notes: +- Translators are not displayed (TO DO) +- "Video Subtitles" heading can be translated when it is added in [`translations.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/translations.yml). (TO DO) ## Technical Details @@ -381,17 +386,17 @@ Features: [WAI Markdown Extension](/writing/wai-markdown/) automatically modifies links to WAI website internal links, based on the following rules. -The extension looks for a translated version of the linked-to page: that is, a page sharing the same [`lang`](/writing/frontmatter/#lang) as the current page, and the same [`ref`](/writing/frontmatter/#ref) as the linked-to page: -- When a translation is found, the links points to the translated page. +The extension looks for a translated version of the linked-to page: that is, a page sharing the same [`lang`](/writing/frontmatter/#lang) as the _current page_, and the same [`ref`](/writing/frontmatter/#ref) as the _linked-to page_: +- When a translation is found, the link points to the translated page. - When no translation is found: - - The links points to the English version; + - The link points to the English version; - `hreflang` attribute is set to `en`; - "(in English)" is added at the end of the link, in the language of the page (if translated in [`translations.yml` {% include_cached external.html %}](https://github.com/w3c/wai-website-data/blob/master/translations.yml)) Link text is defined as follows: - When single-brackets are used: \ Example: `[Custom link text]({%raw%}/{%endraw%}path/to/filename/)` - - The custom link text defined between the brackets is used. + - The custom link text between the brackets is displayed. - When double-brackets are used:\ Example: `[[Title of WAI Page]]({%raw%}/{%endraw%}path/to/filename/)`