fix: sync Crowdin README headings and add tests

Extend README localization sync to manage both heading strings and navigation links in Crowdin, using canonical heading parsing to preserve/repair section emojis across locales. Update validation helpers to generate heading translations, enforce section-count safety, and add node:test coverage for heading source selection, emoji correction, and missing-section failures. Also add an npm test script and run tests in the lint workflow, and update README/workflow naming for the new Virtual Gamepads section and Game Stores emoji change.

Author: ReenigneArcher

.github/workflows/lint.yml

@@ -28,5 +28,8 @@ jobs:
       - name: Lint
         run: npm run lint
 
+      - name: Test
+        run: npm test
+
       - name: Validate README navigation
         run: npm run validate:readme-navigation

.github/workflows/sync-readme-navigation-crowdin.yml

@@ -1,5 +1,5 @@
 ---
-name: Sync README navigation to Crowdin
+name: Sync README headings and navigation to Crowdin
 permissions:
   contents: read
 
@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: npm ci --ignore-scripts
 
-      - name: Update and approve localized README navigation
+      - name: Update and approve localized README headings and navigation
         run: npm run sync:readme-navigation-crowdin
         env:
           CROWDIN_TOKEN: ${{ secrets.CROWDIN_TOKEN }}

README.md

@@ -13,6 +13,7 @@
   <a href="#-game-stores">Game Stores</a> •
   <a href="#-frontends">Frontends</a> •
   <a href="#-virtual-displays">Virtual Displays</a> •
+  <a href="#-virtual-gamepads">Virtual Gamepads</a> •
   <a href="#-scripts">Scripts</a> •
   <a href="#-testing">Testing</a> •
   <a href="#-guides">Guides</a>
@@ -46,7 +47,7 @@
 - [sunshine_utils](https://github.com/designer-living/sunshine_utils) - Utilities for using with Sunshine / Moonlight / Playnite game streaming.
 - [vuinputd](https://github.com/joleuger/vuinputd) - Enabling container-friendly input handling for Sunshine on Linux.
 
-## 🎮 Game Stores
+## 🛒 Game Stores
 - [Epic Games](https://www.epicgames.com) - Download and play PC Games of every genre. They have mods, DLC, and Free Games too! Games for everyone.
 - [GOG](https://www.gog.com) - Download the best classic and new games on Windows, Mac & Linux. A vast selection of titles, DRM-free, with free goodies.
 - [Steam](https://store.steampowered.com) - The ultimate destination for playing, discussing, and creating games.
@@ -64,6 +65,9 @@
 - [VirtualDisplayDriver_Wizard](https://github.com/sofmeright/VirtualDisplayDriver_Wizard) - A GUI tool that can integrate with other software such as Sunshine for efficient manipulation of Indirect Display Driver Sample (IddSample) implementations.
 - [virtual-display-rs](https://github.com/MolotovCherry/virtual-display-rs) - A Windows virtual display driver to add multiple virtual monitors to your PC! For Win10+. Works with VR, obs, streaming software, etc.
 
+## 🎮 Virtual Gamepads
+- [Virtual HID Driver](https://github.com/LizardByte/libvirtualhid) - User-mode virtual gamepads for Windows. Adds more gamepad types to Windows, such as Xbox One|Series, DualSense, Nintendo Switch Pro, and more to come in the future.
+
 ## 📜 Scripts
 - [Dummy Plug Automation](https://github.com/XenHat/dummy-plug-automation) - Automation for remote streaming using a dummy plug on Linux.
 - [FrlToggle](https://github.com/FrogTheFrog/frl-toggle) - Nvidia's Frame Rate Limiter.

package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "lint": "awesome-lint",
     "sync:readme-navigation-crowdin": "node scripts/sync-readme-navigation-crowdin.mjs",
+    "test": "node --test scripts/*.test.mjs",
     "validate:readme-navigation": "node scripts/validate-readme-navigation.mjs"
   },
   "devDependencies": {

scripts/sync-readme-navigation-crowdin.mjs

@@ -1,11 +1,14 @@
 import path from 'node:path'
 import process from 'node:process'
+import { fileURLToPath } from 'node:url'
 
 import { Client as CrowdinClient } from '@crowdin/crowdin-api-client'
 
 import {
+  createHeadingTranslations,
   createNavigationTranslation,
   findLocalizedReadmes,
+  parseCanonicalHeadings,
   parseNavigationLinks
 } from './validate-readme-navigation.mjs'
 
@@ -58,7 +61,25 @@ function createLanguageIds (locales, targetLanguages) {
   return languageIds
 }
 
-async function findNavigationString (crowdin) {
+function findHeadingSources (sourceStrings, navigation) {
+  const navigationLinks = parseNavigationLinks(navigation.text.split(/\r?\n/))
+
+  if (navigationLinks.length === 0) {
+    throw new Error('The Crowdin README navigation source string has no links')
+  }
+
+  return navigationLinks.map(link => {
+    const source = findOne(
+      sourceStrings,
+      `README heading source string for ${link.text}`,
+      item => !item.isHidden && parseCanonicalHeadings([`## ${item.text}`])[0]?.text === link.text
+    )
+    const canonical = parseCanonicalHeadings([`## ${source.text}`])[0]
+    return { canonical, source }
+  })
+}
+
+async function findReadmeStrings (crowdin) {
   const branches = await crowdin.sourceFilesApi.withFetchAll()
     .listProjectBranches(PROJECT_ID)
   const branch = findOne(data(branches), `Crowdin branch named ${BRANCH_NAME}`, item => {
@@ -73,13 +94,22 @@ async function findNavigationString (crowdin) {
 
   const strings = await crowdin.sourceStringsApi.withFetchAll()
     .listProjectStrings(PROJECT_ID, { fileId: readme.id })
+  const sourceStrings = data(strings)
+  const navigation = findOne(
+    sourceStrings,
+    `README navigation string with context ${NAVIGATION_CONTEXT}`,
+    item => item.context === NAVIGATION_CONTEXT
+  )
+  const headings = findHeadingSources(sourceStrings, navigation)
 
-  return findOne(data(strings), `README navigation string with context ${NAVIGATION_CONTEXT}`, item => {
-    return item.context === NAVIGATION_CONTEXT
-  })
+  return {
+    canonicalHeadings: headings.map(heading => heading.canonical),
+    headings: headings.map(heading => heading.source),
+    navigation
+  }
 }
 
-function localizedReadme (localeRoot, file, expectedHeadingCount, languageIds) {
+function localizedReadme (localeRoot, file, canonicalHeadings, languageIds) {
   const relativeFile = path.relative(localeRoot, file)
   const parts = relativeFile.split(path.sep)
 
@@ -91,9 +121,10 @@ function localizedReadme (localeRoot, file, expectedHeadingCount, languageIds) {
   if (!languageId) throw new Error(`No Crowdin language mapping for locale/${parts[0]}`)
 
   return {
-    expected: createNavigationTranslation(file, expectedHeadingCount),
     file: `locale/${parts.join('/')}`,
-    languageId
+    headings: createHeadingTranslations(file, canonicalHeadings),
+    languageId,
+    navigation: createNavigationTranslation(file, canonicalHeadings)
   }
 }
 
@@ -146,6 +177,17 @@ async function synchronizeTranslation (crowdin, stringId, target, dryRun) {
   return actions
 }
 
+function actionVerb (actions, dryRun) {
+  if (actions.length === 0) return 'Checked'
+  if (dryRun) return 'Would update'
+  return 'Updated'
+}
+
+function logActions (target, label, actions, dryRun) {
+  const status = actions.length === 0 ? 'already correct and approved' : actions.join(', ')
+  console.log(`${actionVerb(actions, dryRun)} ${target.file} ${label}: ${status}`)
+}
+
 async function main () {
   const token = process.env.CROWDIN_TOKEN
   if (!token) throw new Error('CROWDIN_TOKEN is required')
@@ -154,45 +196,58 @@ async function main () {
   const root = process.cwd()
   const localeRoot = path.join(root, 'locale')
   const crowdin = new CrowdinClient({ token })
-  const [projectResponse, navigationString] = await Promise.all([
+  const [projectResponse, readmeStrings] = await Promise.all([
     crowdin.projectsGroupsApi.getProject(PROJECT_ID),
-    findNavigationString(crowdin)
+    findReadmeStrings(crowdin)
   ])
-  const expectedHeadingCount = parseNavigationLinks(navigationString.text.split(/\r?\n/)).length
+  const canonicalHeadings = readmeStrings.canonicalHeadings
+  const sourceLinkCount = parseNavigationLinks(readmeStrings.navigation.text.split(/\r?\n/)).length
 
-  if (expectedHeadingCount === 0) {
-    throw new Error('The Crowdin README navigation source string has no links')
+  if (sourceLinkCount !== canonicalHeadings.length) {
+    throw new Error(
+      `The Crowdin README navigation source has ${sourceLinkCount} links; expected ${canonicalHeadings.length}`
+    )
   }
 
   const readmes = findLocalizedReadmes(localeRoot)
   const locales = readmes.map(file => path.relative(localeRoot, path.dirname(file)))
   const languageIds = createLanguageIds(locales, projectResponse.data.targetLanguages)
   const targets = readmes
-    .map(file => localizedReadme(localeRoot, file, expectedHeadingCount, languageIds))
+    .map(file => localizedReadme(localeRoot, file, canonicalHeadings, languageIds))
     .sort((left, right) => left.file.localeCompare(right.file, 'en'))
 
   if (targets.length === 0) throw new Error('No localized README files were found')
 
   for (const target of targets) {
-    const actions = await synchronizeTranslation(
+    for (const [index, heading] of target.headings.entries()) {
+      const actions = await synchronizeTranslation(
+        crowdin,
+        readmeStrings.headings[index].id,
+        { expected: heading, languageId: target.languageId },
+        dryRun
+      )
+      logActions(target, `heading ${index + 1}`, actions, dryRun)
+    }
+
+    const navigationActions = await synchronizeTranslation(
       crowdin,
-      navigationString.id,
-      target,
+      readmeStrings.navigation.id,
+      { expected: target.navigation, languageId: target.languageId },
       dryRun
     )
-    const status = actions.length === 0 ? 'already correct and approved' : actions.join(', ')
-    let verb = 'Updated'
-    if (actions.length === 0) verb = 'Checked'
-    else if (dryRun) verb = 'Would update'
-    console.log(`${verb} ${target.file}: ${status}`)
+    logActions(target, 'navigation', navigationActions, dryRun)
   }
 
-  console.log(`${dryRun ? 'Checked' : 'Synchronized'} ${targets.length} localized README navigation translations.`)
+  console.log(`${dryRun ? 'Checked' : 'Synchronized'} ${targets.length} localized README heading and navigation translations.`)
 }
 
-try {
-  await main()
-} catch (error) {
-  console.error(error)
-  process.exitCode = 1
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    await main()
+  } catch (error) {
+    console.error(error)
+    process.exitCode = 1
+  }
 }
+
+export { findHeadingSources }

scripts/validate-readme-navigation.mjs

@@ -44,6 +44,42 @@ function headingText (markdown) {
     .trim()
 }
 
+function splitHeading (text) {
+  const firstSpace = text.indexOf(' ')
+  const prefix = firstSpace > 0 ? text.slice(0, firstSpace) : ''
+
+  if (/\p{Extended_Pictographic}/u.test(prefix)) {
+    return {
+      emoji: prefix,
+      text: text.slice(firstSpace + 1).trim()
+    }
+  }
+
+  return { emoji: '', text }
+}
+
+function parseCanonicalHeadings (lines) {
+  const headings = []
+
+  for (const line of lines) {
+    const match = /^(#{1,6})[ \t](.+)$/.exec(line)
+    if (!match) continue
+
+    const level = match[1].length
+    const sourceText = headingText(match[2].replace(/[ \t]#+[ \t]*$/, ''))
+    const heading = splitHeading(sourceText)
+
+    if (level === 2 && heading.emoji) {
+      headings.push({
+        emoji: heading.emoji,
+        text: heading.text
+      })
+    }
+  }
+
+  return headings
+}
+
 function parseHeadings (lines) {
   const slugger = new GithubSlugger()
   const navigationHeadings = []
@@ -73,6 +109,53 @@ function parseHeadings (lines) {
   return navigationHeadings
 }
 
+function readLocalizedHeadings (file, canonicalHeadings) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/)
+  const h2Count = lines.filter(line => /^##[ \t]+/.test(line)).length
+
+  if (h2Count <= canonicalHeadings.length) {
+    throw new Error(
+      `${file} has fewer than ${canonicalHeadings.length} navigation headings plus its final section`
+    )
+  }
+
+  const slugger = new GithubSlugger()
+  const headings = []
+  let navigationIndex = 0
+
+  for (const line of lines) {
+    const match = /^(#{1,6})[ \t](.+)$/.exec(line)
+    if (!match) continue
+
+    const level = match[1].length
+    const currentText = headingText(match[2].replace(/[ \t]#+[ \t]*$/, ''))
+    let expectedText = currentText
+
+    if (level === 2 && navigationIndex < canonicalHeadings.length) {
+      const canonical = canonicalHeadings[navigationIndex]
+      const localized = splitHeading(currentText)
+      expectedText = `${canonical.emoji} ${localized.text}`
+      headings.push({
+        expected: expectedText,
+        slug: slugger.slug(expectedText),
+        text: localized.text
+      })
+      navigationIndex++
+      continue
+    }
+
+    slugger.slug(expectedText)
+  }
+
+  if (headings.length !== canonicalHeadings.length) {
+    throw new Error(
+      `${file} has ${headings.length} navigation headings; expected ${canonicalHeadings.length}`
+    )
+  }
+
+  return headings
+}
+
 function parseNavigationLinks (lines) {
   const firstHeading = lines.findIndex(line => /^#{1,6}[ \t]+/.test(line))
   const preambleLines = lines.slice(0, firstHeading === -1 ? lines.length : firstHeading)
@@ -92,15 +175,13 @@ function parseNavigationLinks (lines) {
   return links
 }
 
-function createNavigationTranslation (file, expectedHeadingCount) {
-  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/)
-  const headings = parseHeadings(lines)
+function createHeadingTranslations (file, canonicalHeadings) {
+  return readLocalizedHeadings(file, canonicalHeadings)
+    .map(heading => heading.expected)
+}
 
-  if (headings.length !== expectedHeadingCount) {
-    throw new Error(
-      `${file} has ${headings.length} navigation headings; expected ${expectedHeadingCount}`
-    )
-  }
+function createNavigationTranslation (file, canonicalHeadings) {
+  const headings = readLocalizedHeadings(file, canonicalHeadings)
 
   const links = headings.map((heading, index) => {
     const separator = index === headings.length - 1 ? '' : ' •'
@@ -229,8 +310,10 @@ function main () {
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main()
 
 export {
+  createHeadingTranslations,
   createNavigationTranslation,
   findLocalizedReadmes,
+  parseCanonicalHeadings,
   parseNavigationLinks,
   validateReadme
 }