feat: adding final publishable version

.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: publish
+on:
+    push:
+        tags:
+            - 'v[0-9]+.[0-9]+.[0-9]+*'
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+            - uses: actions/setup-node@v1
+              with:
+                  node-version: 16
+                  registry-url: 'https://registry.npmjs.org'
+            - run: npm ci
+            - run: npm run test
+            - run: npm run build
+            - run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.npmignore

@@ -6,4 +6,5 @@
 .idea
 prettier.config.js
 tsconfig.json
-test/
+test/
+.github/

README.md

@@ -0,0 +1,90 @@
+# Parselt
+
+Parselt (a shortened form of parseltongue) is a library for updating and linting translation files in json or yaml. To get started, see [Getting Started](#getting-started).
+
+# Basic Concepts
+
+Parselt current supports two commands: 'scan' and 'format'. Each of these require a config file (see [Getting Started](#getting-started)) that identifies a main file or a main directory that represents the primary language of your application (e.g. `en.json` or `en/settings.json`).
+
+'Scan' will check all non-main files and compare them to the main files. It will verify that all structures are the same (e.g. that a key in `fr.json` that has an object value doesn't correspond to the same key in `en.json` which has an array value). It will then warn for all keys which are the same across translations and provide errors for any dissimilar structures, invalid values (e.g. null), or keys that are found in the main files, but not found in non-main files.
+
+'Format' mainly serves to re-order keys alphabetically. There is also an option to remove extra translations which are found in non-main files, but not in main files. The use case for this last feature is that users will sometimes delete a translation in the main language when it is removed from use in the application, but forget to apply this to all other translations. Over time, these unused keys increase and create clutter in the application.
+
+# When to use
+
+Parselt will work for applications of all sizes, but medium-to-large applications will see the most benefit. Unsurprisingly, as applications gain more keys and more languages, there is more potential for clutter, which is where parselt excels.
+
+# Getting Started
+
+## Set up a config file
+
+Create a `parselt.json` file at the root of your project with the following property:
+
+```json
+{
+    "instances": []
+}
+```
+
+```json
+
+Now add your first instance with basic properties to the "instances" array:
+
+{
+        "name": string, // e.g. "main". Must be unique per instance
+        "rootDirectoryPath": string, //e.g. "./src/i18n",
+        "shouldCheckFirstKey": boolean, // default: true. Set to false if the first key in the file is not something that is referenced (e.g. your structure is something like, {"EN": {"SETTINGS_TITLE": "Settings"}}, but you only reference the "SETTINGS" key, instead of the full path, "EN.SETTINGS").
+        "shouldPrintResultSummaryOnly": boolean, // default: false
+        "fileType": "json" | "yaml",
+        "indentation": 2 | 4,
+}
+```
+
+If your translation files are in a single directory (e.g. with `en.json`, `fr.json`, etc.), then add the following properties to your instance:
+
+```json
+{
+        "isMultiDirectory": false,
+        "mainFileName": string, //e.g. "en.json"
+        "filePrefix": string | null, //use if you are loading different types of files by prefix in the directory (e.g. you have an en.json and fr.json, as well as an auth.en.json and an auth.fr.json)
+}
+```
+
+If your translation files are in multiple directories (e.g. with `en/settings.json`, `fr/settings.json`, etc.), then add the following properties to your instance:
+
+```json
+{
+        "isMultiDirectory": true,
+        "mainDirectoryName": string, //e.g. "en"
+}
+```
+
+Now you're good to go with your first config file! If you have translation files in multiple places within your application, simply add more instances with a unique name per instance.
+
+## Commands
+
+To scan/format one instance, named "main":
+
+```
+npx parselt scan --instance-name main
+```
+
+```
+npx parselt format --instance-name main
+```
+
+To scan/format all instances:
+
+```
+npx parselt scan
+```
+
+```
+npx parselt format
+```
+
+To remove extra translations in non-main files (e.g. "SETTINGS.KEY1.KEY2" is present in `fr.json`, but not in the main file, `en.json`):
+
+```
+npx parselt format --remove-extras
+```

lib/cli.ts

@@ -1,7 +1,7 @@
 import yargs, { Arguments } from 'yargs'
 import { hideBin } from 'yargs/helpers'
 import * as packageJson from '../package.json'
-import { addTranslationFile, format, scan } from './commands'
+import { format, scan } from './commands'
 import { ConfigLoader } from './config/ConfigLoader'
 
 const configLoader = new ConfigLoader()
@@ -10,34 +10,34 @@ const init = () => {
     yargs(hideBin(process.argv))
         .usage('Usage: $0 <command> --instance-name')
         .version(packageJson.version)
-        .command('add', 'Add translations', (yargs: any) => {
-            return yargs.command(
-                'file',
-                'Add translations file',
-                (yargs: any) => {
-                    return yargs
-                        .option('file-name', {
-                            describe: 'File name for the file that should be added',
-                            type: 'string',
-                            requiresArg: true,
-                        })
-                        .option('instance-name', {
-                            describe: 'Instance name to which the formatting should pertain',
-                            type: 'string',
-                            requiresArg: true,
-                        })
-                        .option('directories', {
-                            describe:
-                                'Directories to which the file should be added (if option is not set, file will be added to all directories',
-                            type: 'string',
-                        }).argv
-                },
-                (argv: Arguments) => {
-                    const config = configLoader.loadAddTranslationFileConfig(argv)
-                    addTranslationFile(config)
-                }
-            )
-        })
+        // .command('add', 'Add translations', (yargs: any) => { //TODO re-add when testing is complete and this is stable.
+        //     return yargs.command(
+        //         'file',
+        //         'Add translations file',
+        //         (yargs: any) => {
+        //             return yargs
+        //                 .option('file-name', {
+        //                     describe: 'File name for the file that should be added',
+        //                     type: 'string',
+        //                     requiresArg: true,
+        //                 })
+        //                 .option('instance-name', {
+        //                     describe: 'Instance name to which the formatting should pertain',
+        //                     type: 'string',
+        //                     requiresArg: true,
+        //                 })
+        //                 .option('directories', {
+        //                     describe:
+        //                         'Directories to which the file should be added (if option is not set, file will be added to all directories',
+        //                     type: 'string',
+        //                 }).argv
+        //         },
+        //         (argv: Arguments) => {
+        //             const config = configLoader.loadAddTranslationFileConfig(argv)
+        //             addTranslationFile(config)
+        //         }
+        //     )
+        // })
         .command(
             'format',
             'Format translation files so that keys are in alphabetical order',

lib/commands.ts

@@ -131,8 +131,8 @@ export const scan = (config: ScanConfig): IScanResult => {
     }
 }
 
-export const addTranslationFile = (config: AddTranslationFileConfig) => {
-    const errorCollector = new ScanningErrorsCollector()
-    const fileService = new FileService(errorCollector)
-    fileService.createFileFromTemplate(config)
-}
+// export const addTranslationFile = (config: AddTranslationFileConfig) => {
+//     const errorCollector = new ScanningErrorsCollector()
+//     const fileService = new FileService(errorCollector)
+//     fileService.createFileFromTemplate(config)
+// }

package.json

@@ -10,6 +10,7 @@
         "node": ">=16.0.0"
     },
     "scripts": {
+        "build": "tsc",
         "test": "jest",
         "clean": "ts-node ./scripts/cleanNonTs.ts"
     },