Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add a way of warning users that localised docs might be out of date #1504

Merged
merged 9 commits into from
Sep 12, 2023
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/asciidoc-pages/docs/faq/index.de.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
= Frequently Asked Questions
:page-authors: gdams, HanSolo, sw-fox, aumann, hendrikebbers
:page-based-on: 56f8f9b0dd04a8cadd21fa9b68ee86430949c0b7

Auf dieser Seite haben wir versucht häufig gestellte Fragen (FAQs) für die Community zu beantworten.
Alle weiteren Fragen können jederzeit gerne in unsere https://adoptium.net/slack.html[Slack-Channel] gestellt
Expand Down
3 changes: 3 additions & 0 deletions content/asciidoc-pages/docs/faq/index.es.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
= Frequently Asked Questions
:page-authors: eddumelendez, czelabueno, jdluna, raulmj, tellison, gdams
:page-based-on: 50dc526fadcdd7dd03b386f112ac1ab4043bb554
gdams marked this conversation as resolved.
Show resolved Hide resolved

Hemos reunido unas cuantas preguntas frecuentes (FAQs) en este documento.
Si quieres conversar con nosotros sobre estos tópicos, o realizar preguntas adicionales
Expand All @@ -22,6 +23,8 @@ action, y parte del soporte de Java de los proveedores de la nube.
Los instaladores de Linux están disponibles en packages.adoptium.net. Para más
información ver link:/installation/linux[esta guía].

== ¿Temurin(TM) es de uso gratuito?

Sí. Los binarios de Eclipse Temurin son proporcionados para su uso sin ningún costo por Adoptium, por siempre, bajo los términos de la "GNU General Public License, version 2 with the
Classpath Exception". Usted puede utilizar, modificar y compartir libremente el código como se describe en las licencias incluidas en la descarga.

Expand Down
1 change: 1 addition & 0 deletions content/asciidoc-pages/docs/faq/index.zh-CN.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
= Frequently Asked Questions
:page-authors: zdtsw, gdams, tellison
:page-based-on: 50dc526fadcdd7dd03b386f112ac1ab4043bb554

在该文件中,我们收集了一些常见问题。如果您想讨论这些话题或有其他问题,最佳途径是通过以下链接
https://adoptium.net/slack.html[Slack] 或者在
Expand Down
4 changes: 2 additions & 2 deletions content/asciidoc-pages/docs/first-timer-support/index.de.adoc
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
= Eclipse Adoptium(R) First Timers Support
:page-authors: gdams, HanSolo, hendrikebbers, tellison
:page-based-on: 50dc526fadcdd7dd03b386f112ac1ab4043bb554
:description: Support with first time contributions
:keywords: adoptium documentation contribute first-time
:lang: en
:icons: font


Wir bei Adoptium(R) wollen Menschen helfen, in OpenSource, Java und die Java Community einzusteigen.
Wir bei Adoptium wollen Menschen helfen, in OpenSource, Java und die Java Community einzusteigen.
gdams marked this conversation as resolved.
Show resolved Hide resolved
Deshalb ist es für uns wichtig, Menschen, die mit OpenSource arbeiten wollen, zu unterstützen.

[NOTE]
Expand Down
1 change: 1 addition & 0 deletions content/asciidoc-pages/docs/migration/index.de.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
= Migration Guide
:page-authors: gdams, HanSolo, MBoegers, hendrikebbers, ojuschugh1
:page-based-on: e0bae585804689459af34ceecc98fe74e8cfc3d6
:icons: font

== Migration zu Eclipse Temurin
Expand Down
1 change: 1 addition & 0 deletions content/asciidoc-pages/docs/qvs-policy/index.de.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
:orgname: Eclipse Adoptium
:lang: en
:page-authors: gdams, HanSolo
:page-based-on: 50dc526fadcdd7dd03b386f112ac1ab4043bb554

== Überblick

Expand Down
19 changes: 18 additions & 1 deletion gatsby-node.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ const crypto = require('crypto')
const path = require('path')
const fetch = require('node-fetch')
const fs = require('fs')
const util = require('node:util')
const exec = util.promisify(require('node:child_process').exec)
const { pipeline } = require('stream')
const { promisify } = require('util')
const { createFilePath } = require('gatsby-source-filesystem')
Expand Down Expand Up @@ -87,7 +89,7 @@ exports.sourceNodes = async ({ actions, createNodeId }) => {
createNode(MostRecentFeatureVersion)
}

exports.onCreatePage = ({ page, actions }) => {
exports.onCreatePage = ({ page, actions, getNodes }) => {
const { createPage, deletePage } = actions

// Delete pages such as /about/index.de
Expand All @@ -109,9 +111,12 @@ exports.onCreatePage = ({ page, actions }) => {
: `${locales[lang].path}${page.path}`

let locale = 'en'
let defaultGitSHA

if (fs.existsSync(`./content/asciidoc-pages${page.path}index.${lang}.adoc`)) {
locale = lang
// fetch fields.gitSHA from the default language file
defaultGitSHA = getNodes().find(n => n.fields && n.fields.slug === page.path).fields.gitSHA || null
}

return createPage({
Expand All @@ -126,6 +131,7 @@ exports.onCreatePage = ({ page, actions }) => {
context: {
...page.context,
locale,
defaultGitSHA,
language: lang,
i18n: {
...page.context.i18n,
Expand Down Expand Up @@ -168,6 +174,17 @@ exports.onCreateNode = async ({ node, actions, getNode, getNodes }) => {
// Find the key that has "default: true" set (in this case it returns "en")
const defaultKey = findKey(locales, o => o.default === true)

if (isDefault) {
// Get Git SHA of the last commit to the file and add it as a field
const gitLastCommitCMD = `git log -1 --format=%H ${fetchFilePath.absolutePath}`
const { stdout, stderr } = await exec(gitLastCommitCMD)
if (stderr) {
console.error(stderr)
}
const gitLastCommit = stdout.trim() || null
gitLastCommit && createNodeField({ node, name: 'gitSHA', value: gitLastCommit })
}

// Files are defined with "name-with-dashes.lang.adoc"
// name returns "name-with-dashes.lang"
// So grab the lang from that string
Expand Down
4 changes: 4 additions & 0 deletions locales/de/asciidoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"asciidoc.template.warn.default.locale": "Dies ist die <englishVersionLink>englische Version</englishVersionLink> der Seite, da aktuell noch keine deutsche Übersetzung verfügbar ist. Du kannst uns helfen diese Seite in deutsch bereitzustellen. In unserem <translationGuideLink>Leitfaden zu Übersetzungen</translationGuideLink> findest du mehr Informationen.",
"asciidoc.template.warn.outdated": "Die deutsche Übersetzung dieser Seite basiert auf einem <previousEnglishVersionLink>nicht mehr aktuellen englischen Text</previousEnglishVersionLink>. Daher ist es Möglich, dass Teile des Textes nicht mehr zutreffen. Du kannst helfen die Seite aktuell zu halten und eine überarbeitete Übersetzung der <lastEnglishVersionLink>aktuellen englischen Seite/lastEnglishVersionLink> bereitzustellen. In unserem <translationGuideLink>Leitfaden zu Übersetzungen</translationGuideLink> findest du mehr Informationen."
}
4 changes: 4 additions & 0 deletions locales/es/asciidoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"asciidoc.template.warn.default.locale": "Esta página es la <englishVersionLink>versión en inglés</englishVersionLink> porque no está disponible en su idioma. Por favor, ayudenos traduciendo esta página a su idioma. Para más información, visite nuestra <translationGuideLink>guía de traducción</translationGuideLink>",
"asciidoc.template.warn.outdated": "La traducción de esta página está basada en una <previousEnglishVersionLink>versión anterior de la página en inglés</previousEnglishVersionLink> y puede ser inexacta. Por favor, ayúdenos actualizando esta página para que coincida con la <lastEnglishVersionLink>última versión de la pagina en inglés</lastEnglishVersionLink>. Para más información, visite nuestra <translationGuideLink>guía de traducción</translationGuideLink>."
}
4 changes: 4 additions & 0 deletions locales/fr/asciidoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"asciidoc.template.warn.default.locale": "Cette page est la <englishVersionLink>version en anglais</englishVersionLink> car elle n'existe pas dans votre langue. Aidez-nous à la traduire en français. Consultez notre <translationGuideLink>guide de traduction</translationGuideLink> pour plus d'informations.",
"asciidoc.template.warn.outdated": "Cette page est la <englishVersionLink>version en anglais</englishVersionLink> car elle n'existe pas dans votre langue. Aidez-nous à traduire la dernière <englishVersionLink>version en anglais</englishVersionLink>. Consultez notre <translationGuideLink>guide de traduction</translationGuideLink> pour plus d'informations."
}
53 changes: 50 additions & 3 deletions src/templates/__tests__/asciidoc.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,15 @@ import { axe } from 'vitest-axe';
import { createAsciidocData } from '../../__fixtures__/page';

let mockData = createAsciidocData();
const pageContext = {
locale: 'en',
defaultGitSHA: '1234567890',
}


describe('Asciidoc pages', () => {
it('renders correctly', () => {
const { container } = render(<AllAsciidocPages data={mockData} />);
const { container } = render(<AllAsciidocPages data={mockData} pageContext />);
// eslint-disable-next-line
const pageContent = container.querySelector('main');

Expand All @@ -25,16 +30,58 @@ describe('Asciidoc pages', () => {

it('renders correctly - installation slug', () => {
mockData.asciidoc.fields.slug = '/installation/';
const { container } = render(<AllAsciidocPages data={mockData} />);
const { container } = render(<AllAsciidocPages data={mockData} pageContext />);
// eslint-disable-next-line
const pageContent = container.querySelector('main');

expect(pageContent).toMatchSnapshot();
});

it('has no accessibility violations', async () => {
const { container } = render(<AllAsciidocPages data={mockData} />);
const { container } = render(<AllAsciidocPages data={mockData} pageContext />);
const results = await axe(container);
expect(results).toHaveNoViolations();
});

it('renders correctly - no warning when translation is up-to-date', () => {
let customMockData = createAsciidocData();
customMockData.asciidoc.pageAttributes.based_on = '1234567890';

let customPageContext = {
locale: 'fr',
language: 'fr',
defaultGitSHA: '1234567890',
}

const { container } = render(<AllAsciidocPages data={customMockData} pageContext={customPageContext} />);

expect(container.getElementsByClassName('alert-warning').length).toBe(0);
});

it('renders correctly - display warning when translation is outdated', () => {
let customMockData = createAsciidocData();
customMockData.asciidoc.pageAttributes.based_on = '0987654321';

let customPageContext = {
locale: 'fr',
language: 'fr',
defaultGitSHA: '1234567890',
}

const { container } = render(<AllAsciidocPages data={customMockData} pageContext={customPageContext} />);

expect(container.getElementsByClassName('alert-warning').length).toBe(1);
});

it('renders correctly - display warning when translation is the default one', () => {
let customPageContext = {
locale: 'en',
language: 'fr',
defaultGitSHA: '1234567890',
}

const { container } = render(<AllAsciidocPages data={mockData} pageContext={customPageContext} />);

expect(container.getElementsByClassName('alert-warning').length).toBe(1);
});
});
43 changes: 40 additions & 3 deletions src/templates/asciidocTemplate.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,28 @@ import EditLink from '../components/EditLink'
import AuthorsList from '../components/AuthorList'
import InstallTabs from '../components/InstallTabs'
import Seo from '../components/Seo'
import { Trans } from 'gatsby-plugin-react-i18next';
import LinkText from '../components/LinkText'

import '@fortawesome/fontawesome-free/css/all.min.css'
import '@fortawesome/fontawesome-free/css/v4-shims.min.css'

const AsciidocTemplate = ({ data }) => {
const AsciidocTemplate = ({ data, pageContext }) => {
useEffect(() => {
asciidocFormatter()
highlightCode()
})
const { asciidoc } = data // data.asciidoc holds our data
const { document, fields, html, pageAttributes } = asciidoc
const pageAuthorList = pageAttributes.authors || ''
const { relativePath } = fields
const basedOnSha = pageAttributes.based_on || ''
const { relativePath, slug } = fields
const { defaultGitSHA, locale, language } = pageContext

// Translated version of the page doesn't exist and isn't en-GB
const displayDefaultLocaleWarning = locale !== language && language !== 'en-GB';
const displayOutdatedWarning = defaultGitSHA && basedOnSha && defaultGitSHA !== basedOnSha;

return (
<Layout>
<section className='py-5 px-3'>
Expand All @@ -31,7 +40,34 @@ const AsciidocTemplate = ({ data }) => {
</div>
<div className='asciidoc col-lg-6 col-md-12'>
<h1 className='pb-4 fw-light text-center' dangerouslySetInnerHTML={{ __html: document.title }} />
{fields.slug === '/installation/' && (
{displayDefaultLocaleWarning && (
<div className='alert alert-warning'>
<i className='fas fa-exclamation-triangle pe-1' />
<Trans
i18nKey='asciidoc.template.warn.default.locale'
defaults='This page is the <englishVersionLink>English version</englishVersionLink> because it is not available in your language. Please help us by translating this page into your language. See our <translationGuideLink>translation guide</translationGuideLink> for more information.'
components={{
englishVersionLink: <LinkText href={`https://github.com/adoptium/adoptium.net/blob/main/content/asciidoc-pages/${relativePath.replace(`.${locale}`, '')}`} />,
translationGuideLink: <LinkText href='https://github.com/adoptium/adoptium.net/tree/main/content/asciidoc-pages#localising-documentation' />
}}
/>
</div>
)}
{displayOutdatedWarning && (
<div className='alert alert-warning'>
<i className='fas fa-exclamation-triangle pe-1' />
<Trans
i18nKey='asciidoc.template.warn.outdated'
defaults='This localized page is based on a <previousEnglishVersionLink>previous version of the English page</previousEnglishVersionLink> and might be inaccurate. Please help us by updating this page to match the <lastEnglishVersionLink>latest version of the English page</lastEnglishVersionLink>. See our <translationGuideLink>translation guide</translationGuideLink> for more information.'
components={{
previousEnglishVersionLink: <LinkText href={`https://github.com/adoptium/adoptium.net/blob/${basedOnSha}/content/asciidoc-pages/${relativePath.replace(`.${locale}`, '')}`} />,
lastEnglishVersionLink: <LinkText href={`https://github.com/adoptium/adoptium.net/blob/main/content/asciidoc-pages/${relativePath.replace(`.${locale}`, '')}`} />,
translationGuideLink: <LinkText href='https://github.com/adoptium/adoptium.net/tree/main/content/asciidoc-pages#localising-documentation' />
}}
/>
</div>
)}
{slug === '/installation/' && (
<section className='adopt-demo-container hide-on-mobile my-5'>
<div className='adopt-demo mx-auto'>
<InstallTabs />
Expand Down Expand Up @@ -77,6 +113,7 @@ export const pageQuery = graphql`
}
pageAttributes {
authors
based_on
}
}
locales: allLocale(filter: {language: {eq: $language}}) {
Expand Down
1 change: 1 addition & 0 deletions src/types/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ export interface AsciidocPage {
},
pageAttributes: {
authors: string;
based_on?: string;
}
}

Expand Down