Merge pull request #265 from cesarParra/translations

Translations

Author: cesarParra

README.md

@@ -12,6 +12,26 @@ ApexDocs is a non-opinionated documentation generator for Salesforce Apex classe
 It can output documentation in Markdown format, which allows you to use the Static Site Generator of your choice to
 create a documentation site that fits your needs, hosted in any static web hosting service.
 
+## Table of Contents
+
+- [👀 Examples](#-examples)
+- [🚀 Features](#-features)
+- [💿 Installation](#-installation)
+- [⚡ Quick Start](#-quick-start)
+  - [CLI](#cli)
+    - [Markdown](#markdown)
+    - [OpenApi](#openapi)
+    - [Changelog](#changelog)
+- [▶️ Available Commands](#️-available-commands)
+  - [Markdown](#markdown-1)
+  - [OpenApi](#openapi-1)
+  - [Changelog](#changelog-1)
+- [🔬 Defining a configuration file](#-defining-a-configuration-file)
+- [🌐 Translation](#-translation)
+- [⤵︎ Importing to your project](#︎-importing-to-your-project)
+- [📖 Documentation Guide](#-documentation-guide)
+- [📄 Generating OpenApi REST Definitions](#-generating-openapi-rest-definitions)
+
 ## 👀 Examples
 
 ApexDocs generates Markdown files, which can be integrated into any Static Site Generation (SSG) engine,
@@ -64,6 +84,7 @@ Here are some live projects using ApexDocs:
 * Support for ignoring files and members from being documented
 * Namespace support
 * Configuration file support
+* Translation support for different languages and custom terminology
 * Single line ApexDoc Blocks
 * Custom tag support
 * And much, much more!
@@ -274,6 +295,12 @@ export default defineMarkdownConfig({
   sourceDir: 'force-app',
   targetDir: 'docs',
   scope: ['global', 'public'],
+  translations: {
+    sections: {
+      methods: 'Methods',
+      properties: 'Properties',
+    },
+  },
   ...
 });
 ```
@@ -595,6 +622,74 @@ export default {
 };
 ```
 
+## 🌐 Translation
+
+ApexDocs supports translations to customize the language and terminology used in the generated documentation.
+This feature allows you to:
+
+- **Translate documentation to different languages** (Spanish, French, etc.)
+- **Use custom business terminology** (e.g., "Business Operations" instead of "Methods")
+- **Partially override specific terms** while keeping the rest in English
+
+### How It Works
+
+The translation system uses:
+
+- **Default English translations** built into the system
+- **User-provided overrides** that can be partial or complete
+
+### Configuration
+
+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';
+
+export default defineMarkdownConfig({
+  sourceDir: 'src',
+  targetDir: 'docs',
+  scope: ['public', 'global'],
+  translations: {
+    sections: {
+      methods: 'Métodos',
+      properties: 'Propiedades',
+      fields: 'Campos',
+    },
+  },
+});
+```
+
+### TypeScript Support
+
+For TypeScript projects, import the translation types for better autocomplete and type safety:
+
+```typescript
+import { defineMarkdownConfig } from '@cparra/apexdocs';
+import type { UserTranslations } from '@cparra/apexdocs';
+
+const markdownTranslations: UserTranslations['markdown'] = {
+  sections: {
+    methods: 'Functions',
+  },
+  // ...other translation keys as needed
+};
+
+export default defineMarkdownConfig({
+  sourceDir: 'src',
+  targetDir: 'docs',
+  scope: ['public', 'global'],
+  translations: markdownTranslations,
+});
+```
+
+### Notes
+
+- Only the **markdown** and **changelog** generators support translations
+- All translations are optional - anything not specified uses the English default
+
+For a complete example, see the [translation example](examples/translation/) in this repository.
+
 ## ⤵︎ Importing to your project
 
 ### Reflection

examples/translation/.forceignore

@@ -0,0 +1,12 @@
+# List files or directories below to ignore them when running force:source:push, force:source:pull, and force:source:status
+# More information: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_exclude_source.htm
+#
+
+package.xml
+
+# LWC configuration files
+**/jsconfig.json
+**/.eslintrc.json
+
+# LWC Jest
+**/__tests__/**

examples/translation/README.md

@@ -0,0 +1,62 @@
+# Sample Project With Provided Translations
+
+Demonstrates how to provide translations to ApexDocs to customize the language and terminology used in generated documentation.
+
+## Overview
+
+The translation feature allows you to:
+
+1. **Translate documentation to different languages** (Spanish, French, etc.)
+2. **Use custom business terminology** (e.g., "Business Operations" instead of "Methods")
+3. **Partially override specific terms** while keeping the rest in English
+
+## Configuration
+
+Add a `translations` property to your ApexDocs configuration:
+
+```javascript
+import { defineMarkdownConfig } from '@cparra/apexdocs';
+
+export default defineMarkdownConfig({
+  sourceDir: 'src',
+  targetDir: 'docs',
+  scope: ['public', 'global'],
+  translations: {
+    // Your custom translations here
+    sections: {
+      methods: 'Métodos',
+      properties: 'Propiedades',
+      fields: 'Campos',
+    },
+  },
+});
+```
+
+## TypeScript Support
+
+If you're using TypeScript, you can import the translation types for better autocomplete and type safety:
+
+```typescript
+import { defineMarkdownConfig } from '@cparra/apexdocs';
+import type { UserTranslations } from '@cparra/apexdocs';
+
+const translations: UserTranslations = {
+  markdown: {
+    sections: {
+      methods: 'Functions',
+    },
+  },
+};
+
+export default defineMarkdownConfig({
+  sourceDir: 'src',
+  targetDir: 'docs',
+  scope: ['public', 'global'],
+  translations: translations.markdown,
+});
+```
+
+## Notes
+
+- Only the **markdown** and **changelog** generators support translations
+- All translations are optional - anything not specified uses the English default

examples/translation/apexdocs.config.ts

@@ -0,0 +1,49 @@
+import { defineChangelogConfig, 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',
+  },
+};
+
+export default {
+  markdown: defineMarkdownConfig({
+    sourceDir: 'force-app',
+    scope: ['global', 'public'],
+    translations: spanishTranslations,
+  }),
+  changelog: defineChangelogConfig({
+    previousVersionDir: 'previous',
+    currentVersionDir: 'force-app',
+    scope: ['global', 'public'],
+    translations: {
+      title: 'Registro de Cambios',
+    },
+  }),
+};

examples/translation/config/project-scratch-def.json

@@ -0,0 +1,5 @@
+{
+  "orgName": "cesarparra company",
+  "edition": "Developer",
+  "features": []
+}

examples/translation/docs/changelog.md

@@ -0,0 +1,77 @@
+# Registro de Cambios
+
+## New Classes
+
+These classes are new.
+
+### BaseClass
+
+### MultiInheritanceClass
+
+### Url
+
+Represents a uniform resource locator (URL) and provides access to parts of the URL. 
+Enables access to the base URL used to access your Salesforce org.
+### SampleClass
+
+aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
+**deserunt** ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+### SampleException
+
+This is a sample exception.
+
+## New Interfaces
+
+These interfaces are new.
+
+### ParentInterface
+
+### SampleInterface
+
+This is a sample interface
+
+## New Enums
+
+These enums are new.
+
+### ReferencedEnum
+
+### SampleEnum
+
+This is a sample enum. This references ReferencedEnum . 
+ 
+This description has several lines
+
+## New Custom Objects
+
+These custom objects are new.
+
+### Account
+
+### Contact
+
+### Event__c
+
+Represents an event that people can register for.
+### Price_Component__c
+
+### Product_Price_Component__c
+
+### Product__c
+
+Product that is sold or available for sale.
+### Sales_Order_Line__c
+
+Represents a line item on a sales order.
+### Sales_Order__c
+
+Custom object for tracking sales orders.
+### Speaker__c
+
+Represents a speaker at an event.
+
+## Removed Custom Objects
+
+These custom objects have been removed.
+
+- VisibleCMT__mdt

examples/translation/docs/custom-objects/Account.md

@@ -0,0 +1,4 @@
+# Account
+
+## Nombre API
+`Account`

examples/translation/docs/custom-objects/Contact.md

@@ -0,0 +1,15 @@
+# Contact
+
+## Nombre API
+`Contact`
+
+## Campos
+### PhotoUrl
+
+**Nombre API**
+
+`PhotoUrl__c`
+
+**Tipo**
+
+*Url*