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

…1504)

* rebase

* fix failing test

* linter fixes

* Add missing coverage for AsciidocTemplate

* [AsciidocTemplate] add banner that alerts users to viewing an English page that hasn’t been translated

* [AsciidocTemplate] warning boxes need to be translated

* add more locales and skip on en-GB

* Update asciidoc.json

* Update content/asciidoc-pages/docs/first-timer-support/index.de.adoc

Co-authored-by: Hendrik Ebbers <hendrik.ebbers@web.de>

---------

Co-authored-by: Xavier FACQ <xavier.facq@free.fr>
Co-authored-by: Hendrik Ebbers <hendrik.ebbers@web.de>

content/asciidoc-pages/docs/faq/index.de.adoc

@@ -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

content/asciidoc-pages/docs/faq/index.es.adoc

@@ -1,5 +1,6 @@
 = Frequently Asked Questions
 :page-authors: eddumelendez, czelabueno, jdluna, raulmj, tellison, gdams
+:page-based-on: 50dc526fadcdd7dd03b386f112ac1ab4043bb554
 
 Hemos reunido unas cuantas preguntas frecuentes (FAQs) en este documento.
 Si quieres conversar con nosotros sobre estos tópicos, o realizar preguntas adicionales 
@@ -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.
 

content/asciidoc-pages/docs/faq/index.zh-CN.adoc

@@ -1,5 +1,6 @@
 = Frequently Asked Questions
 :page-authors: zdtsw, gdams, tellison
+:page-based-on: 50dc526fadcdd7dd03b386f112ac1ab4043bb554
 
 在该文件中，我们收集了一些常见问题。如果您想讨论这些话题或有其他问题，最佳途径是通过以下链接
 https://adoptium.net/slack.html[Slack] 或者在

content/asciidoc-pages/docs/first-timer-support/index.de.adoc

@@ -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 unterstützen, in OpenSource, Java und die Java Community einzusteigen.
 Deshalb ist es für uns wichtig, Menschen, die mit OpenSource arbeiten wollen, zu unterstützen.
 
 [NOTE]

content/asciidoc-pages/docs/migration/index.de.adoc

@@ -1,5 +1,6 @@
 = Migration Guide
 :page-authors: gdams, HanSolo, MBoegers, hendrikebbers, ojuschugh1
+:page-based-on: e0bae585804689459af34ceecc98fe74e8cfc3d6
 :icons: font
 
 == Migration zu Eclipse Temurin

content/asciidoc-pages/docs/qvs-policy/index.de.adoc

@@ -4,6 +4,7 @@
 :orgname: Eclipse Adoptium
 :lang: en
 :page-authors: gdams, HanSolo
+:page-based-on: 50dc526fadcdd7dd03b386f112ac1ab4043bb554
 
 == Überblick
 

gatsby-node.js

@@ -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')
@@ -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
@@ -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({
@@ -126,6 +131,7 @@ exports.onCreatePage = ({ page, actions }) => {
           context: {
             ...page.context,
             locale,
+            defaultGitSHA,
             language: lang,
             i18n: {
               ...page.context.i18n,
@@ -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

locales/de/asciidoc.json

@@ -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."
+}

locales/es/asciidoc.json

@@ -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 no ser exacta. 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>."
+}

locales/fr/asciidoc.json

@@ -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."
+}

src/templates/__tests__/asciidoc.test.tsx

@@ -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');
 
@@ -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);
+  });
 });

src/templates/asciidocTemplate.tsx

@@ -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'>
@@ -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 />
@@ -77,6 +113,7 @@ export const pageQuery = graphql`
       }
       pageAttributes {
         authors
+        based_on
       }
     }
     locales: allLocale(filter: {language: {eq: $language}}) {

src/types/index.tsx

@@ -11,6 +11,7 @@ export interface AsciidocPage {
     },
     pageAttributes: {
         authors: string;
+        based_on?: string;
     }
 }