Refine translation config typing and usage for markdown and changelog generators

Author: cesarParra

README.md

@@ -27,7 +27,7 @@ create a documentation site that fits your needs, hosted in any static web hosti
   - [OpenApi](#openapi-1)
   - [Changelog](#changelog-1)
 - [🔬 Defining a configuration file](#-defining-a-configuration-file)
-- [🌐 Translation](#-translation-support)
+- [🌐 Translation](#-translation)
 - [⤵︎ Importing to your project](#︎-importing-to-your-project)
 - [📖 Documentation Guide](#-documentation-guide)
 - [📄 Generating OpenApi REST Definitions](#-generating-openapi-rest-definitions)
@@ -296,11 +296,9 @@ export default defineMarkdownConfig({
   targetDir: 'docs',
   scope: ['global', 'public'],
   translations: {
-    markdown: {
-      sections: {
-        methods: 'Methods',
-        properties: 'Properties',
-      },
+    sections: {
+      methods: 'Methods',
+      properties: 'Properties',
     },
   },
   ...
@@ -633,8 +631,6 @@ This feature allows you to:
 - **Use custom business terminology** (e.g., "Business Operations" instead of "Methods")
 - **Partially override specific terms** while keeping the rest in English
 
-Translation is supported for the `markdown` and `changelog` generators.
-
 ### How It Works
 
 The translation system uses:
@@ -644,7 +640,8 @@ The translation system uses:
 
 ### Configuration
 
-Add a `translations` property to your ApexDocs configuration (JS or TS file):
+Add a `translations` property to your ApexDocs configuration (JS or TS file) and pass
+the appropriate translation object, depending on the generator you're using:
 
 ```javascript
 import { defineMarkdownConfig } from '@cparra/apexdocs';
@@ -654,12 +651,10 @@ export default defineMarkdownConfig({
   targetDir: 'docs',
   scope: ['public', 'global'],
   translations: {
-    markdown: {
-      sections: {
-        methods: 'Métodos',
-        properties: 'Propiedades',
-        fields: 'Campos',
-      },
+    sections: {
+      methods: 'Métodos',
+      properties: 'Propiedades',
+      fields: 'Campos',
     },
   },
 });
@@ -673,35 +668,25 @@ For TypeScript projects, import the translation types for better autocomplete an
 import { defineMarkdownConfig } from '@cparra/apexdocs';
 import type { UserTranslations } from '@cparra/apexdocs';
 
-const translations: UserTranslations = {
-  markdown: {
-    sections: {
-      methods: 'Functions',
-    },
+const markdownTranslations: UserTranslations['markdown'] = {
+  sections: {
+    methods: 'Functions',
   },
+  // ...other translation keys as needed
 };
 
 export default defineMarkdownConfig({
   sourceDir: 'src',
   targetDir: 'docs',
   scope: ['public', 'global'],
-  translations,
+  translations: markdownTranslations,
 });
 ```
 
-### Best Practices
-
-1. **Start Small**: Begin with partial translations for the most important terms
-2. **Be Consistent**: Use the same terminology across your organization
-3. **Test Thoroughly**: Generate documentation with your translations to verify the output
-4. **Version Control**: Include your translation configurations in version control
-
 ### Notes
 
 - Only the **markdown** and **changelog** generators support translations
-- The **OpenAPI** generator does not use the translation system
 - All translations are optional - anything not specified uses the English default
-- The system uses deep merging, so partial translations work seamlessly
 
 For a complete example, see the [translation example](examples/translation/) in this repository.
 

examples/translation/apexdocs.config.ts

@@ -1,36 +1,34 @@
 import { defineMarkdownConfig, UserTranslations } from '../../src';
 
 // Spanish translations
-const spanishTranslations: UserTranslations = {
-  markdown: {
-    sections: {
-      methods: 'Métodos',
-      properties: 'Propiedades',
-      fields: 'Campos',
-      constructors: 'Constructores',
-      namespace: 'Espacio de Nombres',
-      values: 'Valores',
-    },
-    details: {
-      apiName: 'Nombre API',
-      type: 'Tipo',
-      signature: 'Firma',
-      parameters: 'Parámetros',
-      returnType: 'Tipo de Retorno',
-      throws: 'Lanza',
-      required: 'Requerido',
-      author: 'Autor',
-    },
-    typeSuffixes: {
-      class: 'Clase',
-      interface: 'Interfaz',
-      enum: 'Enum',
-      trigger: 'Disparador',
-    },
-    inheritance: {
-      inheritance: 'Herencia',
-      implements: 'Implementa',
-    },
+const spanishTranslations: UserTranslations['markdown'] = {
+  sections: {
+    methods: 'Métodos',
+    properties: 'Propiedades',
+    fields: 'Campos',
+    constructors: 'Constructores',
+    namespace: 'Espacio de Nombres',
+    values: 'Valores',
+  },
+  details: {
+    apiName: 'Nombre API',
+    type: 'Tipo',
+    signature: 'Firma',
+    parameters: 'Parámetros',
+    returnType: 'Tipo de Retorno',
+    throws: 'Lanza',
+    required: 'Requerido',
+    author: 'Autor',
+  },
+  typeSuffixes: {
+    class: 'Clase',
+    interface: 'Interfaz',
+    enum: 'Enum',
+    trigger: 'Disparador',
+  },
+  inheritance: {
+    inheritance: 'Herencia',
+    implements: 'Implementa',
   },
 };
 

src/core/changelog/generate-change-log.ts

@@ -39,7 +39,7 @@ export function generateChangeLog(
     if (config.skipIfNoChanges && !hasChanges(changelog)) {
       return skip();
     }
-    const translations = mergeTranslations(config.translations);
+    const translations = mergeTranslations({ changelog: config.translations });
     return pipe(
       convertToRenderableChangelog(changelog, newManifest.types, translations),
       compile(translations),

src/core/markdown/adapters/renderable-to-page-data.ts

@@ -1,4 +1,4 @@
-import { ReferenceGuideReference, Renderable, RenderableBundle, RenderableEnum } from '../../renderables/types';
+import { ReferenceGuideReference, Renderable, RenderableBundle } from '../../renderables/types';
 import { DocPageData, DocumentationBundle } from '../../shared/types';
 import { pipe } from 'fp-ts/function';
 import { CompilationRequest, Template } from '../../template';

src/core/markdown/generate-docs.ts

@@ -49,7 +49,7 @@ export type MarkdownGeneratorConfig = Omit<
 };
 
 export function generateDocs(unparsedBundles: UnparsedSourceBundle[], config: MarkdownGeneratorConfig) {
-  const translations = mergeTranslations(config.translations);
+  const translations = mergeTranslations({ markdown: config.translations });
   const convertToReferences = apply(parsedFilesToReferenceGuide, config);
   const convertToRenderableBundle = apply(parsedFilesToRenderableBundle, config);
   const convertToDocumentationBundleForTemplate = apply(

src/core/shared/types.d.ts

@@ -49,7 +49,7 @@ export type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   excludeTags: string[];
   exclude: string[];
-  translations?: UserTranslations;
+  translations?: UserTranslations['markdown'];
 } & CliConfigurableMarkdownConfig &
   Partial<MarkdownConfigurableHooks>;
 
@@ -76,7 +76,7 @@ export type UserDefinedChangelogConfig = {
   customObjectVisibility: string[];
   exclude: string[];
   skipIfNoChanges: boolean;
-  translations?: UserTranslations;
+  translations?: UserTranslations['changelog'];
 } & Partial<ChangelogConfigurableHooks>;
 
 export type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig | UserDefinedChangelogConfig;