Feature: translate descriptions

examples/docgen-vite/package.json

@@ -27,7 +27,7 @@
  "typescript": "~4.7.4",
  "vite": "^2.9.14",
  "vitepress": "^1.0.0-alpha.13",
- "vue-component-meta": "^0.40.13",
+ "vue-component-meta": "^1.0.8",
  "vue-docgen-cli": "^4",
  "vue-live": "^2",
  "vue-tsc": "^0.38.8"

package.json

@@ -109,6 +109,7 @@
  "vue": "2.7.11",
  "vue-cli-plugin-docgen": "*",
  "vue-cli-plugin-styleguidist": "*",
+ "vue-docgen-i18n": "*",
  "vue-inbrowser-compiler-sucrase": "*",
  "vue-property-decorator": "9.1.2",
  "vue-server-renderer": "2.7.11",
@@ -158,4 +159,4 @@
  "[email protected]": "patches/[email protected]"
  }
  }
-}
+}

packages/vue-docgen-api/package.json

@@ -38,13 +38,15 @@
  "lru-cache": "^4.1.5",
  "pug": "^3.0.2",
  "recast": "0.21.5",
+ "traverse": "^0.6.6",
  "ts-map": "^1.0.3",
  "vue-inbrowser-compiler-independent-utils": "^4.52.0"
  },
  "devDependencies": {
  "@test-vue-docgen/mixins": "^4.44.15",
  "@types/dedent": "0.7.0",
  "@types/pug": "2.0.6",
+ "@types/traverse": "^0.6.32",
  "dedent": "0.7.0",
  "globby": "10.0.2",
  "vue": "2.7.11",
@@ -53,4 +55,4 @@
  "vue-property-decorator": "7.3.0",
  "vuetify": "2.6.10"
  }
-}
+}

packages/vue-docgen-api/src/main.ts

@@ -10,18 +10,22 @@ import Documentation, {
  ParamTag,
  ParamType
 } from './Documentation'
-import { DocGenOptions, parseFile, ParseOptions, parseSource as _parseSource } from './parse'
+import { DocGenOptions as DCOptions, parseFile, ParseOptions, parseSource as _parseSource } from './parse'
 import * as ScriptHandlers from './script-handlers'
 import * as TemplateHandlers from './template-handlers'
+import mergeTranslations from './mergeTranslations'
 
 export { ScriptHandlers }
 export { TemplateHandlers }
 
+export interface DocGenOptions extends DCOptions {
+ translation?: string
+}
+
 export { TemplateParserOptions } from './parse-template'
 export { ScriptHandler, TemplateHandler } from './parse'
 export {
  ComponentDoc,
- DocGenOptions,
  ParseOptions,
  Documentation,
  BlockTag,
@@ -77,8 +81,9 @@ export async function parseSource(
 function isOptionsObject(opts: any): opts is DocGenOptions {
  return (
  !!opts &&
- (!!opts.alias ||
- opts.jsx !== undefined ||
+ (opts.jsx !== undefined ||
+ !!opts.alias ||
+ !!opts.validExtends ||
  !!opts.addScriptHandlers ||
  !!opts.addTemplateHandlers)
  )
@@ -101,5 +106,7 @@ async function parsePrimitive(
  validExtends: (fullFilePath: string) => !/[\\/]node_modules[\\/]/.test(fullFilePath)
  }
  const docs = await createDocs(options)
- return docs.map(d => d.toObject())
+ return docs
+ .map(d => d.toObject())
+ .map(d => (opts && opts.translation ? mergeTranslations(d, filePath, opts.translation) : d))
 }

packages/vue-docgen-api/src/mergeTranslations.test.ts

@@ -0,0 +1,68 @@
+import { expect } from 'vitest'
+import { mergeTranslationsAsObject } from './mergeTranslations'
+
+const trad = [
+ {
+ name: 'default',
+ description: "un example de traduction d'un composant",
+ props: [
+ {
+ name: 'size',
+ description: 'taille du bouton'
+ },
+ {
+ name: 'span',
+ description: 'nombre de colomnes'
+ }
+ ]
+ }
+]
+
+const orig = {
+ exportName: 'default',
+ displayName: 'origin',
+ tags: {},
+ description:
+ 'This is an example of creating a reusable button component and using it with external data.',
+ props: [
+ {
+ name: 'span',
+ description: 'Number of columns (1-12) the column should span.'
+ },
+ {
+ name: 'spanSm',
+ description: 'Sm breakpoint and above'
+ },
+ {
+ name: 'size',
+ description: 'The size of the button'
+ }
+ ]
+}
+
+describe('mergeTranslationsAsObject', () => {
+ it('should match the object', () => {
+ expect(mergeTranslationsAsObject(orig, trad)).toMatchInlineSnapshot(`
+ {
+ "description": "un example de traduction d'un composant",
+ "displayName": "origin",
+ "exportName": "default",
+ "props": [
+ {
+ "description": "nombre de colomnes",
+ "name": "span",
+ },
+ {
+ "description": "Sm breakpoint and above",
+ "name": "spanSm",
+ },
+ {
+ "description": "taille du bouton",
+ "name": "size",
+ },
+ ],
+ "tags": {},
+ }
+ `)
+ })
+})

packages/vue-docgen-api/src/mergeTranslations.ts

@@ -0,0 +1,61 @@
+import * as path from 'path'
+import traverse from 'traverse'
+import { ComponentDoc } from './Documentation'
+
+export function getTranslationsObjectFromFile(fullFilePath: string, translation: string) {
+ const transFileName = `${path.basename(fullFilePath).replace(/\.\w+$/, '')}.${translation}.js`
+ return require(path.join(path.dirname(fullFilePath), transFileName))
+}
+
+export function mergeTranslationsAsObject(docs: ComponentDoc, transObjects: any[]): ComponentDoc {
+ const transObject = transObjects.find((tr: { name: string }) => tr.name === docs.exportName)
+ traverse(transObject).forEach(function(traversedItem) {
+ if (!traversedItem.description) {
+ return
+ }
+ // if the element is in array
+ if (this.key && !isNaN(parseInt(this.key, 10)) && this.parent) {
+ if (!traversedItem.name) return
+ // find path of array
+ const arrayPath = this.parent.path
+ // get element in doc
+ let i = 0
+ let obj = docs
+ while (i < arrayPath.length) {
+ obj = obj[arrayPath[i++]]
+ // if element does not exist quit
+ if (!obj) return
+ }
+ const arrayOfProps = obj
+ const prop = arrayOfProps.find((p: any) => p.name === traversedItem.name)
+ // update its description with the one provided
+ if (traversedItem.description && prop) {
+ prop.description = traversedItem.description
+ }
+ } else {
+ const arrayPath = this.path
+ // get element in doc
+ let i = 0
+ let obj = docs
+ while (i < arrayPath.length) {
+ obj = obj[arrayPath[i++]]
+ // if element does not exist quit
+ if (!obj) return
+ }
+ // update its description with the one provided
+ if (traversedItem.description) {
+ obj.description = traversedItem.description
+ }
+ }
+ })
+ return docs
+}
+
+export default function mergeTranslations(
+ docs: ComponentDoc,
+ fullFilePath: string,
+ translation: string
+): ComponentDoc {
+ const transObjects = getTranslationsObjectFromFile(fullFilePath, translation)
+ return mergeTranslationsAsObject(docs, transObjects)
+}

packages/vue-docgen-api/src/template-handlers/slotHandler.test.ts

@@ -180,7 +180,7 @@ describe('slotHandler', () => {
  )
  traverse(ast.children[0], doc, [slotHandler], ast.children, { functional: false })
  const slots = doc.toObject().slots || []
- expect(slots.filter(s => s.name === 'bound')[0].bindings).toMatchObject([
+ expect(slots.filter((s: any) => s.name === 'bound')[0].bindings).toMatchObject([
  {
  name: 'v-bind'
  }
@@ -198,7 +198,7 @@ describe('slotHandler', () => {
  )
  traverse(ast.children[0], doc, [slotHandler], ast.children, { functional: false })
  const slots = doc.toObject().slots || []
- expect(slots.filter(s => s.name === 'bound')[0].bindings).toMatchObject([
+ expect(slots.filter((s: any) => s.name === 'bound')[0].bindings).toMatchObject([
  {
  name: 'item'
  },
@@ -223,7 +223,7 @@ describe('slotHandler', () => {
  )
  traverse(ast.children[0], doc, [slotHandler], ast.children, { functional: false })
  const slots = doc.toObject().slots || []
- expect(slots.filter(s => s.name === 'bound')[0].bindings).toMatchObject([
+ expect(slots.filter((s: any) => s.name === 'bound')[0].bindings).toMatchObject([
  {
  name: 'item',
  description: 'menu item'

packages/vue-docgen-api/src/utils/documentRequiredComponents.ts

@@ -39,6 +39,7 @@ export default async function documentRequiredComponents(
  for (const varName of Object.keys(varToFilePath)) {
  const { filePath, exportName } = varToFilePath[varName]
  filePath.forEach(p => {
+ if (!opt.validExtends(p)) return
  const fullFilePath = pathResolver(p)
  if (fullFilePath && opt.validExtends(fullFilePath)) {
  const vars = files.get(fullFilePath) || []
@@ -88,6 +89,7 @@ async function enrichDocumentation(
  // long as we follow the variables order
  await Promise.all(
  filePath.map(async p => {
+ if (!opt.validExtends(p)) return
  const fullFilePath = pathResolver(p)
 
  if (fullFilePath && opt.validExtends(fullFilePath)) {

packages/vue-docgen-api/src/utils/recursiveResolveIEV.ts

@@ -81,10 +81,12 @@ export async function resolveIEV(
  }
  })
  try {
+ if (!validExtends(filePath)) return
  const fullFilePath = pathResolver(filePath)
  if (!fullFilePath || !validExtends(fullFilePath)) {
  return
  }
+
  const source = await read(fullFilePath, {
  encoding: 'utf-8'
  })

packages/vue-docgen-api/tests/components/button/Button.FR.js

@@ -0,0 +1,92 @@
+module.exports = [
+ {
+ name: 'default',
+ /* @orig: This is an example of creating a reusable button component and using it with external data.*/
+ description:
+ 'This is an example of creating a reusable button component and using it with external data.',
+ props: [
+ {
+ name: 'span',
+ /* @orig: Number of columns (1-12) the column should span.*/
+ description: 'Number of columns (1-12) the column should span.'
+ },
+ {
+ name: 'spanSm',
+ /* @orig: Sm breakpoint and above*/
+ description: 'Sm breakpoint and above'
+ },
+ {
+ name: 'size',
+ /* @orig: The size of the button*/
+ description: 'taille du bouton'
+ },
+ {
+ name: 'spanMd',
+ /* @orig: Md breakpoint and above*/
+ description: 'Md breakpoint and above'
+ },
+ {
+ name: 'example',
+ /* @orig: The example props*/
+ description: 'The example props'
+ },
+ {
+ name: 'v-model',
+ /* @orig: Model example2*/
+ description: 'Model example2'
+ },
+ {
+ name: 'example3',
+ /* @orig: The example3 props*/
+ description: 'The example3 props'
+ },
+ {
+ name: 'onCustomClick',
+ /* @orig: Add custom click actions.*/
+ description: 'Add custom click actions.'
+ },
+ {
+ name: 'funcDefault',
+ /* @orig: Function default*/
+ description: 'Function default'
+ },
+ {
+ name: 'propE',
+ /* @orig: Object or array defaults must be returned from
+a factory function*/
+ description: 'Object or array defaults must be returned from\na factory function'
+ }
+ ],
+ events: [
+ {
+ name: 'success',
+ /* @orig: Success event.*/
+ description: 'Success event.',
+ properties: [
+ {
+ name: 'demo',
+ /* @orig: example*/
+ description: 'example'
+ },
+ {
+ name: 'called',
+ /* @orig: test called*/
+ description: 'test called'
+ },
+ {
+ name: 'isPacked',
+ /* @orig: Indicates whether the snowball is tightly packed.*/
+ description: 'Indicates whether the snowball is tightly packed.'
+ }
+ ]
+ }
+ ],
+ slots: [
+ {
+ name: 'default',
+ /* @orig: Use this slot default*/
+ description: 'Use this slot default'
+ }
+ ]
+ }
+]