Migrate to modules and expose plugin function

.github/workflows/npm-ci.yml

@@ -5,24 +5,23 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ master, zkolev/use-ga ]
+    branches: [master]
   pull_request:
-    branches: [ master, zkolev/use-ga ]
+    branches: [master]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [14.x]
+        node-version: [22.x]
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm ci
-    - run: npm run build
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm run build

.github/workflows/npm-publish.yml

@@ -1,6 +1,3 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-
 name: Node.js Deploy
 
 on:
@@ -11,18 +8,37 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
-          node-version: 12
-          registry-url: 'https://registry.npmjs.org'
+          node-version: 22
+          cache: "npm"
+          registry-url: "https://registry.npmjs.org"
+
       - run: echo "VERSION=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_ENV
       - run: echo ${VERSION}
-      - run: npm ci
-      - run: npm run build
-      - run: if [[ ${VERSION} == *"alpha"* || ${VERSION} == *"beta"* || ${VERSION} == *"rc"* ]]; then echo "NPM_TAG=next"; else echo "NPM_TAG=latest"; fi >> $GITHUB_ENV
-      - run: echo ${NPM_TAG}
-      - run: npm version ${VERSION} --no-git-tag-version --save --verbose
-      - run: npm publish --tag ${NPM_TAG}
-        env: 
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Define NPM tag
+        run: |
+          if [[ ${VERSION} == *"alpha"* || ${VERSION} == *"beta"* || ${VERSION} == *"rc"* ]]; then 
+            echo "NPM_TAG=next";
+          else 
+            echo "NPM_TAG=latest";
+          fi >> $GITHUB_ENV
+          echo ${NPM_TAG}
+
+      - name: Create package version
+        run: npm version ${VERSION} --no-git-tag-version --save --verbose
+        working-directory: ./
+
+      - name: Publish sassdoc-plugin-localization
+        run: npm publish --tag ${NPM_TAG}
+        working-directory: ./
+        env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Ignite UI
+Copyright (c) 2025 Ignite UI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,41 +1,63 @@
-## Inspired and used by [igniteui-angular](https://github.com/IgniteUI/igniteui-angular)
-[![Build Status](https://travis-ci.org/IgniteUI/sassdoc-plugin-localization.svg?branch=master)](https://travis-ci.org/IgniteUI/sassdoc-plugin-localization)
+## SassDoc Plugin Localization for Ignite UI
 [![npm version](https://badge.fury.io/js/sassdoc-plugin-localization.svg)](https://badge.fury.io/js/sassdoc-plugin-localization)
 
-Localizer for [Sassdoc](http://sassdoc.com/)
+A localization plugin for [SassDoc](http://sassdoc.com/) specifically designed to work with the [Ignite UI SassDoc Theme](https://github.com/IgniteUI/igniteui-sassdoc-theme).
 
-When using [Sassdoc](http://sassdoc.com/) for API docs generation you may want to generate documentation with different languages.
-
-By using the [package](https://www.npmjs.com/package/sassdoc-plugin-localization) you will be able to:
- 1. Merge all sass declarations that needs localization in a couple of json files.
- 2. Translate them.
- 3. Use the updated files to build a documentation for an entire project in the desired language.
+This plugin enables you to generate multilingual documentation for your Sass codebase by:
+1. Exporting all sass declarations that need localization into JSON files
+2. Giving you the option to translate the content in these JSON files
+3. Importing the translated content to build documentation in different languages
 
 ### Installing
 
-```
+```sh
 npm install sassdoc-plugin-localization --save-dev
 ```
 
+### Configuration
+
+The plugin must be configured in your SassDoc configuration file. Here's an example configuration:
+
+```json
+{
+  "theme": "./node_modules/igniteui-sassdoc-theme",
+  "dest": "./site",
+  "autofill": ["throw", "content"],
+  "display": {
+    "alias": true,
+    "access": ["public", "private"]
+  },
+  "plugins": [
+    {
+      "name": "sassdoc-plugin-localization",
+      "path": "./node_modules/sassdoc-plugin-localization/dist/index.js",
+      "options": {
+        "dir": "extras",
+        "mode": "export"
+      }
+    }
+  ]
+}
+```
+
+#### Plugin Options
+
+- **dir**: The directory where JSON files will be exported to or imported from
+- **mode**: Determines the plugin's operation mode
+  - `export`: Only exports the JSON files for translation
+  - `import`: Only imports and applies translations from JSON files
+  - `both`: Performs both export and import operations. Useful for pass-through builds.
+
 ### Usage
 
-#### Important notes
-> Please take in mind that you are running your local npm packages by `npx` right before the command execution.
-> <br />
-> The alternative would be to install the plugin globally with `-g` at the end of the command.
-> <br />
-> Then you won't need to use `npx`.
+> [!IMPORTANT]
+> This plugin is specifically designed to work with the Ignite UI SassDoc Theme.
 
-#### Step 1
-In order to generate the json representations of each sass decalaration you will have to use one of the exposed functions which is [convert](https://github.com/IgniteUI/sassdoc-plugin-localization/blob/master/src/converter/convert.ts). 
-<br />
-The function accepts:
- 1. The retrieved data which comes from the context of [Sassdoc](http://sassdoc.com/)
- 2. The directory where you would like to export your jsons.
+#### Step 1: Export Sass Declarations to JSON
 
-> As you can see the function is using [sassdoc-extras](https://www.npmjs.com/package/sassdoc-extras) in order to group the data so that the structure of the jsons to be grouped and sorted by types.
+When running SassDoc with the plugin configured in `export` mode, the plugin will generate JSON files containing all the text that can be localized.
 
-More precisely let's say we have the following sass definition:
+For example, given this Sass definition:
 
 ```scss
 ////
@@ -46,56 +68,41 @@ More precisely let's say we have the following sass definition:
 /// @access private
 /// @param {String} $s - The selector to be converted.
 /// @returns {String}
-///
 @function bem--selector-to-string($s) {
-    @if $s == null {
+    @if not($s) {
         @return '';
     }
-    //cast to string
-    $s: inspect($s);
-    @if str-index($s, '(') {
-        // ruby sass => "(selector,)"
-        @return str-slice($s, 2, -3);
-    } @else {
-        // libsass => "selector"
-        @return str-slice($s, 1, -1);
-    }
+
+    @return string.slice(meta.inspect($s), 2, -3);
 }
 ```
-Which says us that we have a sass definition with name **bem--selector-to-string** type **function** and group **bem**. So when we pass the processed data 
-from the [Sassdoc](http://sassdoc.com/) and group it we would have the following directory structure:
-<br />
-**./your-path/bem/function.json** 
-<br />
-and this file would contains the following **JSON** structure:
+
+The plugin will generate a JSON file at `./your-path/bem/function.json` with the following structure:
+
 ```json
 {
     "bem--selector-to-string": {
         "description": [
-            "<p>Converts a passed selector value into plain string.</p>",
-            ""
+            "Converts a passed selector value into plain string."
         ],
         "parameters": {
             "s": {
                 "description": [
-                    "<p>The selector to be converted.</p>",
-                    ""
+                    "The selector to be converted."
                 ]
             }
         }
-    },
-    ...
+    }
 }
 ```
 
-#### Step 2
-Do the translations and update the text within the jsons.
+#### Step 2: Translate the JSON Files
+
+Translate the content in the generated JSON files to your target language(s). You can do this manually or use translation services.
+
+#### Step 3: Generate Documentation with Translations
 
-#### Step 3
-To apply the changes that you have applied in those json files you will have to use the second exported function which is [render](https://github.com/IgniteUI/sassdoc-plugin-localization/blob/master/src/renderer/render.ts) 
-<br />
-The function accepts the same arguments as the [convert](https://github.com/IgniteUI/sassdoc-plugin-localization/blob/master/src/converter/convert.ts) function:
- 1. The retrieved data which comes from the context of [Sassdoc](http://sassdoc.com/)
- 2. The directory where your json file lives.
+Run SassDoc with the plugin configured in `import` mode to generate documentation using your translated JSON files.
 
-The function would compare and replace the generated data from the [Sassdoc](http://sassdoc.com/) with the translated data from the **JSONS**.
+> [!TIP]
+> If you want to see this plugin in action take a look at [igniteui-angular](https://github.com/IgniteUI/igniteui-angular)