docs: localize custom game speed generator

Author: Belonit

docs/.vitepress/theme/components/CustomGameSpeedGenerator.vue

@@ -1,7 +1,7 @@
 <template>
   <div class="custom-game-speed-generator">
     <label class="custom-game-speed-generator__label" for="custom-game-speed-generator-input">
-      Enter desired FPS
+      {{ localizedMessages.desiredFpsLabel }}
     </label>
     <input
       id="custom-game-speed-generator-input"
@@ -12,61 +12,128 @@
       step="1"
       type="number"
     />
-    <p class="custom-game-speed-generator__caption">Results (remember to replace N with your game speed number!):</p>
-    <div class="language-ini vp-adaptive-theme">
-      <button title="Copy Code" class="copy"></button>
+    <p class="custom-game-speed-generator__caption">{{ localizedMessages.resultsCaption }}</p>
+    <div v-if="highlightedCodeHtml" class="language-ini vp-adaptive-theme">
+      <button :aria-label="localizedMessages.copyCode" :title="localizedMessages.copyCode" class="copy"></button>
       <span class="lang">ini</span>
       <pre
         class="shiki shiki-themes github-light github-dark vp-code"
         tabindex="0"
-      ><code v-html="highlightedCodeHtml"></code></pre>
+      ><code v-html="highlightedCodeHtml" />
+    </pre>
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
 import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { useData } from 'vitepress'
 import { createHighlighterCore } from 'shiki/core'
 import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
 import ini from '@shikijs/langs/ini'
 import githubDark from '@shikijs/themes/github-dark'
 import githubLight from '@shikijs/themes/github-light'
 
+const localizedStrings = {
+  'en-US': {
+    desiredFpsLabel: 'Enter desired FPS',
+    resultsCaption: 'Results (remember to replace N with your game speed number!):',
+    copyCode: 'Copy Code',
+    noResults: "Sorry, couldn't find anything!",
+    or: 'Or',
+  },
+  'zh-CN': {
+    desiredFpsLabel: '输入所需的 FPS',
+    resultsCaption: '结果（别忘了把 N 替换成你的游戏速度编号）：',
+    copyCode: '复制代码',
+    noResults: '抱歉，未找到任何结果！',
+    or: '或',
+  },
+} as const
+
+const fallbackLocale = 'en-US'
+const minGameSpeedDelay = 0
+const maxStableGameSpeedDelay = 5
+const minChangeInterval = 1
+const maxChangeInterval = 40
+
+type LocalizationLocale = keyof typeof localizedStrings
+
 type GameSpeedMatch = {
   defaultDelay: number
   changeDelay: number
   changeInterval: number
 }
 
+const { lang } = useData()
 const desiredFps = ref<number>(30)
-const highlightedCodeHtml = ref<string>('')
-let highlightRequestId = 0
 
 const highlighterPromise = createHighlighterCore({
   langs: [ini],
   themes: [githubLight, githubDark],
   engine: createJavaScriptRegexEngine(),
 })
 
-function calculateFps(changeDelay: number, defaultDelay: number, changeInterval: number): number {
-  return (
-    (60 / (6 - changeDelay) + (60 / (6 - defaultDelay)) * ((changeInterval - 1) / (6 - changeDelay))) /
-    (1 + (changeInterval - 1) / (6 - changeDelay))
-  )
-}
+const localizedMessages = computed(() => {
+  return localizedStrings[lang.value as LocalizationLocale] || localizedStrings[fallbackLocale]
+})
+
+const matchingGameSpeedSettings = computed(() => {
+  return findMatchingGameSpeedSettings(desiredFps.value)
+})
+
+const resultText = computed(() => {
+  if (!matchingGameSpeedSettings.value.length) {
+    return `; ${localizedMessages.value.noResults}`
+  }
 
-const matches = computed<GameSpeedMatch[]>(() => {
-  const fps = Number(desiredFps.value)
+  const settings = matchingGameSpeedSettings.value
+    .map((match, index) => formatGameSpeedMatch(match, index, localizedMessages.value.or))
+    .join('\n')
+
+  return `[General]\nCustomGS=true\n;\n${settings}`
+})
+const highlightedCodeHtml = ref<String | null>(null)
 
+let highlightRequestId = 0
+watch(
+  resultText,
+  async (code: string) => {
+    // Shiki is loaded asynchronously; ignore stale highlights if the user
+    // changes FPS again before the previous highlight request finishes.
+    const requestId = (highlightRequestId += 1)
+    highlightedCodeHtml.value = escapeHtml(code)
+
+    const highlighter = await highlighterPromise
+    const highlightedHtml = highlighter.codeToHtml(code, {
+      lang: 'ini',
+      themes: {
+        light: 'github-light',
+        dark: 'github-dark',
+      },
+    })
+
+    if (requestId !== highlightRequestId) {
+      return
+    }
+
+    highlightedCodeHtml.value = normalizeVitePressShikiTokenStyles(extractCodeHtml(highlightedHtml, code))
+  },
+  { immediate: true },
+)
+
+function findMatchingGameSpeedSettings(fps: number): GameSpeedMatch[] {
   if (!Number.isFinite(fps)) {
     return []
   }
 
   const result: GameSpeedMatch[] = []
 
-  for (let defaultDelay = 0; defaultDelay <= 5; defaultDelay += 1) {
-    for (let changeDelay = 0; changeDelay <= 5; changeDelay += 1) {
-      for (let changeInterval = 1; changeInterval <= 40; changeInterval += 1) {
+  // The game accepts delay values, not FPS directly. Try every stable
+  // combination and keep the ones that round to the requested frame rate.
+  for (let defaultDelay = minGameSpeedDelay; defaultDelay <= maxStableGameSpeedDelay; defaultDelay += 1) {
+    for (let changeDelay = minGameSpeedDelay; changeDelay <= maxStableGameSpeedDelay; changeDelay += 1) {
+      for (let changeInterval = minChangeInterval; changeInterval <= maxChangeInterval; changeInterval += 1) {
         if (Math.round(calculateFps(changeDelay, defaultDelay, changeInterval)) === fps) {
           result.push({ defaultDelay, changeDelay, changeInterval })
         }
@@ -75,36 +142,28 @@ const matches = computed<GameSpeedMatch[]>(() => {
   }
 
   return result
-})
-
-const resultText = computed(() => {
-  if (!matches.value.length) {
-    return "// Sorry, couldn't find anything!"
-  }
+}
 
-  return matches.value
-    .map((match, index) => {
-      const lines = [
-        `CustomGSN.DefaultDelay=${match.defaultDelay}`,
-        `CustomGSN.ChangeDelay=${match.changeDelay}`,
-        `CustomGSN.ChangeInterval=${match.changeInterval}`,
-      ]
+function formatGameSpeedMatch(match: GameSpeedMatch, index: number, orLabel: string): string {
+  const lines = [
+    `CustomGSN.DefaultDelay=${match.defaultDelay}`,
+    `CustomGSN.ChangeDelay=${match.changeDelay}`,
+    `CustomGSN.ChangeInterval=${match.changeInterval}`,
+  ]
 
-      if (index > 0) {
-        lines.unshift('// -- Or --')
-      }
+  if (index > 0) {
+    lines.unshift(`; -- ${orLabel} --`)
+  }
 
-      return lines.join('\n')
-    })
-    .join('\n')
-})
+  return lines.join('\n')
+}
 
 function escapeHtml(value: string): string {
   return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
 }
 
-function extractCodeHtml(html: string): string {
-  return html.match(/<code>([\s\S]*)<\/code>/)?.[1] || escapeHtml(resultText.value)
+function extractCodeHtml(html: string, fallbackCode: string): string {
+  return html.match(/<code>([\s\S]*)<\/code>/)?.[1] || escapeHtml(fallbackCode)
 }
 
 function normalizeVitePressShikiTokenStyles(html: string): string {
@@ -126,6 +185,8 @@ function normalizeVitePressShikiTokenStyles(html: string): string {
       const property = declaration.slice(0, separatorIndex).trim()
       const value = declaration.slice(separatorIndex + 1).trim()
 
+      // VitePress themes expect Shiki colors in CSS variables so the same
+      // generated markup can switch between light and dark mode.
       if (property === 'color') {
         lightColor = value
         continue
@@ -142,31 +203,14 @@ function normalizeVitePressShikiTokenStyles(html: string): string {
   })
 }
 
-const stopHighlightWatcher = watch(
-  resultText,
-  async code => {
-    const requestId = (highlightRequestId += 1)
-    highlightedCodeHtml.value = escapeHtml(code)
-
-    const highlighter = await highlighterPromise
-    const highlightedHtml = highlighter.codeToHtml(code, {
-      lang: 'ini',
-      themes: {
-        light: 'github-light',
-        dark: 'github-dark',
-      },
-    })
-
-    if (requestId !== highlightRequestId) {
-      return
-    }
-
-    highlightedCodeHtml.value = normalizeVitePressShikiTokenStyles(extractCodeHtml(highlightedHtml))
-  },
-  { immediate: true },
-)
-
-onBeforeUnmount(stopHighlightWatcher)
+function calculateFps(changeDelay: number, defaultDelay: number, changeInterval: number): number {
+  // CustomGS alternates one changed-delay frame with a run of default-delay
+  // frames. This weighted average estimates the resulting visible FPS.
+  return (
+    (60 / (6 - changeDelay) + (60 / (6 - defaultDelay)) * ((changeInterval - 1) / (6 - changeDelay))) /
+    (1 + (changeInterval - 1) / (6 - changeDelay))
+  )
+}
 </script>
 
 <style scoped>

docs/cspell.json

@@ -7,5 +7,8 @@
     //
     "./package.json"
   ],
-  "words": ["vitepress"]
+  "words": [
+    "Shiki", //
+    "vitepress"
+  ]
 }

docs/locale/zh_CN/LC_MESSAGES/Miscellanous.po

@@ -223,12 +223,6 @@ msgstr "目前无法直接设置所需的 FPS。需要使用下面的生成器
 msgid "Click to show the generator"
 msgstr "点击显示生成器"
 
-msgid "Enter desired FPS"
-msgstr "输入所需的 FPS"
-
-msgid "Results (remember to replace N with your game speed number!):"
-msgstr "结果（别忘了把 N 替换成你的游戏速度编号）："
-
 msgid "Include files"
 msgstr "包含文件"