Merge pull request #24 from Serchinastico/format-command

Format command

Author: Serchinastico

README.md

@@ -81,6 +81,19 @@ linguito translate ~/Development/my-app --llm
 linguito translate ~/Development/my-app --llm --interactive
 ```
 
+### `linguito format`
+
+Reads and cleans the project's catalog files to ensure consistency and readability. It removes empty translations and normalizes the format of the catalog files, making them easier to maintain. This command is particularly useful before committing translation changes to version control or when preparing files for translation work.
+
+#### Examples
+
+```shell
+# Format catalog files in the current directory project
+linguito format
+
+# Or specify a custom project directory
+linguito format ~/Development/my-app
+```
 
 ## Development
 

src/commands/format.ts

@@ -0,0 +1,26 @@
+import {Args} from '@oclif/core'
+
+import BaseCommand from '@/lib/command/base.js'
+import {ConfigParser} from '@/lib/lingui/parser.js'
+import {Translations} from '@/lib/lingui/translations.js'
+
+export default class Format extends BaseCommand {
+  static args = {
+    projectDir: Args.file({default: '.', description: 'Project root directory', required: false}),
+  }
+  static description = `Reads and cleans the project's '.po' catalog files to ensure there are no empty translations.`
+  static examples = [`<%= config.bin %> <%= command.id %> ./my-app`]
+  static summary = 'Cleans commented translations in catalog files.'
+
+  async run() {
+    const {args} = await this.parse(Format)
+    const {projectDir} = args
+
+    const {directory, file: linguiConfigFilePath} = await this.getConfigFile(projectDir)
+    const linguiConfigFileParser = new ConfigParser(directory)
+    const translationsChecker = new Translations(directory)
+
+    const catalogFiles = await linguiConfigFileParser.parse(linguiConfigFilePath)
+    await translationsChecker.format(catalogFiles)
+  }
+}

src/lib/lingui/gettext-parser.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs/promises'
+
+import {invariant} from '@/lib/command/invariant'
+
+type Translation = {
+  comments: string[]
+  msgid: string[]
+  msgstr: string[]
+}
+
+export class GetTextParser {
+  constructor() {}
+
+  async parse(catalogFilePath: string): Promise<Translation[]> {
+    const catalogFile = await fs.readFile(catalogFilePath, 'utf-8')
+    const lines = catalogFile.split('\n')
+
+    const translations: Translation[] = []
+    let currentTranslation: Translation | undefined = undefined
+
+    for (const line of lines) {
+      if (line.startsWith('#')) {
+        if (currentTranslation && currentTranslation.msgstr.length > 0) {
+          translations.push(currentTranslation)
+          currentTranslation = {comments: [line], msgid: [], msgstr: []}
+        } else if (currentTranslation) {
+          currentTranslation?.comments.push(line)
+        } else {
+          currentTranslation = {comments: [line], msgid: [], msgstr: []}
+        }
+      } else if (line.startsWith('msgid')) {
+        if (currentTranslation && currentTranslation.msgstr.length > 0) {
+          translations.push(currentTranslation)
+          currentTranslation = {comments: [], msgid: [line], msgstr: []}
+        } else if (currentTranslation) {
+          currentTranslation.msgid.push(line)
+        } else {
+          currentTranslation = {comments: [], msgid: [line], msgstr: []}
+        }
+      } else if (line.startsWith('msgstr')) {
+        invariant(currentTranslation !== undefined, 'internal_error')
+
+        currentTranslation.msgstr.push(line)
+      } else if (line.startsWith('"')) {
+        invariant(currentTranslation !== undefined, 'internal_error')
+
+        if (currentTranslation.msgstr.length > 0) {
+          currentTranslation.msgstr.push(line)
+        } else {
+          currentTranslation.msgid.push(line)
+        }
+      } else if (line.trim().length === 0) {
+        if (currentTranslation) {
+          translations.push(currentTranslation)
+          currentTranslation = undefined
+        }
+      }
+    }
+
+    return translations
+  }
+}

src/lib/lingui/translations.ts

@@ -4,9 +4,14 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 
 import {FilledTranslation, MissingTranslation} from '@/lib/common/types.js'
+import {GetTextParser} from '@/lib/lingui/gettext-parser'
 
 export class Translations {
-  constructor(private projectDir: string) {}
+  private parser: GetTextParser
+
+  constructor(private projectDir: string) {
+    this.parser = new GetTextParser()
+  }
 
   async addMissing(translations: FilledTranslation[]) {
     const translationsByCatalog = groupBy(translations, (translation) => translation.file)
@@ -25,7 +30,20 @@ export class Translations {
     }
   }
 
-  async getMissing(catalogFiles: string[]) {
+  async format(catalogFiles: string[]) {
+    for (const catalogFile of catalogFiles) {
+      const translations = await this.parser.parse(catalogFile)
+
+      const rebuiltContent = translations
+        .filter((translation) => translation.msgid.length > 0)
+        .map((translation) => [...translation.comments, ...translation.msgid, ...translation.msgstr, ''].join('\n'))
+        .join('\n')
+
+      await fs.writeFile(catalogFile, rebuiltContent)
+    }
+  }
+
+  async getMissing(catalogFiles: string[]): Promise<MissingTranslation[]> {
     const missingTranslations: MissingTranslation[] = []
 
     for (const catalogFile of catalogFiles) {

test/commands/format.test.ts

@@ -0,0 +1,42 @@
+import {runCommand} from '@oclif/test'
+import {expect} from 'chai'
+import fs from 'node:fs/promises'
+import {afterEach, beforeEach, describe, it, vi} from 'vitest'
+
+import {backupCatalogTestFiles, restoreCatalogTestFiles} from '../lib/fs.js'
+
+describe('format', () => {
+  beforeEach(async () => {
+    await backupCatalogTestFiles('all-translations-included')
+    await backupCatalogTestFiles('commented-translations')
+    vi.restoreAllMocks()
+  })
+
+  afterEach(async () => {
+    await restoreCatalogTestFiles('all-translations-included')
+    await restoreCatalogTestFiles('commented-translations')
+  })
+  it('no changes when runs format command in a well-formed project', async () => {
+    const enCatalogFile = await fs.readFile('test/fixtures/all-translations-included/messages.en.po', 'utf-8')
+
+    const {error} = await runCommand('format test/fixtures/all-translations-included')
+
+    const newEnCatalogFile = await fs.readFile('test/fixtures/all-translations-included/messages.en.po', 'utf-8')
+
+    expect(error).to.be.undefined
+    expect(newEnCatalogFile).to.equal(enCatalogFile)
+  })
+
+  it('removes commented translations', async () => {
+    const enCatalogFile = await fs.readFile('test/fixtures/commented-translations/messages.en.po', 'utf-8')
+
+    const {error} = await runCommand('format test/fixtures/commented-translations')
+
+    const newEnCatalogFile = await fs.readFile('test/fixtures/commented-translations/messages.en.po', 'utf-8')
+
+    expect(error).to.be.undefined
+    expect(newEnCatalogFile).to.not.equal(enCatalogFile)
+    expect(enCatalogFile).to.contain('#~ msgstr "{0} of {1}"')
+    expect(newEnCatalogFile).to.not.contain('#~ msgstr "{0} of {1}"')
+  })
+})

test/fixtures/commented-translations/lingui.config.js

@@ -0,0 +1,9 @@
+/** @type {import("@lingui/conf").LinguiConfig} */
+export const locales = ['en']
+export const catalogs = [
+  {
+    include: ['src'],
+    path: '<rootDir>/messages.{locale}',
+  },
+]
+export const format = 'po'

test/fixtures/commented-translations/messages.en.po

@@ -0,0 +1,28 @@
+msgid ""
+msgstr ""
+"POT-Creation-Date: 2024-09-13 14:14+0200\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Generator: @lingui/cli\n"
+"Language: en\n"
+"Project-Id-Version: \n"
+"Report-Msgid-Bugs-To: \n"
+"PO-Revision-Date: \n"
+"Last-Translator: \n"
+"Language-Team: \n"
+"Plural-Forms: \n"
+
+#: src/features/tools/hooks/pdf/usePdfExporter.ts:63
+msgid "{0} - Manual"
+msgstr "{0} - Manual"
+
+#: src/features/image-viewer/components/Header.tsx:24
+#: src/features/image-viewer/components/Footer.tsx:34
+#~ msgid "{0} of {1}"
+#~ msgstr "{0} of {1}"
+
+#: src/features/settings/components/AppPurchasePrompt.tsx:18
+#: src/features/image-viewer/components/AppPurchasePrompt.tsx:34
+msgid "<0><1>Support us in this project and get the app with no limitations </1><2>forever</2><3>.</3></0>"
+msgstr "<0><1>Support us in this project and get the app with no limitations </1><2>forever</2><3>.</3></0>"

test/lib/fs.ts

@@ -1,5 +1,24 @@
+import {CopyOptions} from 'node:fs'
 import fs from 'node:fs/promises'
 
+const cpIfExists = async (source: string, destination: string, options: CopyOptions = {}) => {
+  try {
+    await fs.access(source)
+    await fs.cp(source, destination, options)
+  } catch {
+    /* empty */
+  }
+}
+
+const rmIfExists = async (path: string) => {
+  try {
+    await fs.access(path)
+    await fs.rm(path)
+  } catch {
+    /* empty */
+  }
+}
+
 /**
  * Asynchronously creates backups of test fixture files for the specified test case.
  *
@@ -14,10 +33,10 @@ import fs from 'node:fs/promises'
  *                  to back up (e.g., 'missing-translations').
  * @returns A promise that resolves when all backup operations are complete.
  */
-export const backupCatalogTestFiles = async (fixture: 'missing-translations') => {
+export const backupCatalogTestFiles = async (fixture: string) => {
   await Promise.all([
-    fs.cp(`test/fixtures/${fixture}/messages.en.po`, `test/fixtures/${fixture}/messages.en.po.backup`, {}),
-    fs.cp(`test/fixtures/${fixture}/messages.es.po`, `test/fixtures/${fixture}/messages.es.po.backup`, {}),
+    cpIfExists(`test/fixtures/${fixture}/messages.en.po`, `test/fixtures/${fixture}/messages.en.po.backup`),
+    cpIfExists(`test/fixtures/${fixture}/messages.es.po`, `test/fixtures/${fixture}/messages.es.po.backup`),
   ])
 }
 
@@ -32,14 +51,14 @@ export const backupCatalogTestFiles = async (fixture: 'missing-translations') =>
  *                  Example: 'missing-translations'
  * @returns A promise that resolves once the restoration process is complete.
  */
-export const restoreCatalogTestFiles = async (fixture: 'missing-translations') => {
+export const restoreCatalogTestFiles = async (fixture: string) => {
   await Promise.all([
-    fs.cp(`test/fixtures/${fixture}/messages.en.po.backup`, `test/fixtures/${fixture}/messages.en.po`, {}),
-    fs.cp(`test/fixtures/${fixture}/messages.es.po.backup`, `test/fixtures/${fixture}/messages.es.po`, {}),
+    cpIfExists(`test/fixtures/${fixture}/messages.en.po.backup`, `test/fixtures/${fixture}/messages.en.po`),
+    cpIfExists(`test/fixtures/${fixture}/messages.es.po.backup`, `test/fixtures/${fixture}/messages.es.po`),
   ])
 
   await Promise.all([
-    fs.rm(`test/fixtures/${fixture}/messages.en.po.backup`),
-    fs.rm(`test/fixtures/${fixture}/messages.es.po.backup`),
+    rmIfExists(`test/fixtures/${fixture}/messages.en.po.backup`),
+    rmIfExists(`test/fixtures/${fixture}/messages.es.po.backup`),
   ])
 }