🧩 eslint-plugin-spfx-loc-checker

An ESLint plugin for validating localization consistency and usage across .d.ts interface files and translation files in SharePoint Framework (SPFx) or TypeScript projects.

It enforces two main rules:

• ✅ match-loc-keys – Ensures translation files match the declared keys in the .d.ts interface (no missing or extra keys).
• 🔍 require-used-keys – Ensures all declared localization keys are actually used in your TypeScript/React code.

📦 Installation

1. Install the plugin

npm install eslint-plugin-spfx-loc-checker --save-dev

2. Make sure you have TypeScript and ESLint set up

npm install eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

⚙️ Configuration

In your project root, add (or update) your .eslintrc.js / .eslintrc.cjs:

module.exports = {
  parser: "@typescript-eslint/parser",
  plugins: ["spfx-loc-checker"],
  ignorePatterns: ['!**/mystrings.d.ts'],
  extends: ['@microsoft/eslint-config-spfx/lib/profiles/react', 'plugin:spfx-loc-checker/recommended'],
};

Or enable rules manually:

module.exports = {
  parser: "@typescript-eslint/parser",
  plugins: ["spfx-loc-checker"],
  ignorePatterns: ['!**/mystrings.d.ts'],
  rules: {
    "spfx-loc-checker/match-loc-keys": "error",
    "spfx-loc-checker/require-used-keys": ["warn", { rootDir: "./src" }]
  }
};

🧠 Rule Documentation

🔹 1. match-loc-keys

Purpose:
Ensures that localization interface keys (.d.ts) match all corresponding translation files (.js / .ts) in the nearest loc/ folder.

Checks:

• Missing keys in translation files → ❌ error
• Extra keys not declared in the .d.ts interface → ❌ error

Example structure:

src/webparts/myWebPart/loc/
│
├── mystrings.d.ts
├── en-us.js
└── fr-fr.js

mystrings.d.ts

declare interface IHelloWorldWebPartStrings {
  PropertyPaneDescription: string;
  BasicGroupName: string;
  DescriptionFieldLabel: string;
  AppLocalEnvironmentSharePoint: string;
  AppLocalEnvironmentTeams: string;
  AppLocalEnvironmentOffice: string;
  AppLocalEnvironmentOutlook: string;
  AppSharePointEnvironment: string;
  AppTeamsTabEnvironment: string;
  AppOfficeEnvironment: string;
  AppOutlookEnvironment: string;
  UnknownEnvironment: string; 
}

declare module 'HelloWorldWebPartStrings' {
  const strings: IHelloWorldWebPartStrings;
  export = strings;
}

en-us.js

define([], function() {
  return {
    "PropertyPaneDescription": "Description",
    "BasicGroupName": "Group Name",
    "DescriptionFieldLabel": "Description Field",
    "AppLocalEnvironmentSharePoint": "The app is running on your local environment as SharePoint web part",
    "AppLocalEnvironmentTeams": "The app is running on your local environment as Microsoft Teams app",
    "AppLocalEnvironmentOffice": "The app is running on your local environment in office.com",
    "AppLocalEnvironmentOutlook": "The app is running on your local environment in Outlook",
    "AppSharePointEnvironment": "The app is running on SharePoint page",
    "AppTeamsTabEnvironment": "The app is running in Microsoft Teams",
    "AppOfficeEnvironment": "The app is running in office.com",
    "AppOutlookEnvironment": "The app is running in Outlook",
    "UnknownEnvironment": "The app is running in an unknown environment"
  }
});

✅ All keys match → no issues.
❌ If fr-fr.js misses "Button.Save", ESLint will report:

Missing translation for key "Button.Save" in language "fr-fr.js"

🔹 2. require-used-keys

Purpose:
Ensures that all declared localization keys in your .d.ts interfaces are actually used in your SPFx or TypeScript codebase.

How it works:

• Scans your entire project (excluding node_modules, dist, etc.) for code using strings.<key>.
• Collects all keys from .d.ts files in loc/ folders.
• Warns if a declared key is never referenced in code.

Example:

mystrings.d.ts

declare interface IHelloWorldWebPartStrings {
  PropertyPaneDescription: string;
  BasicGroupName: string;
  DescriptionFieldLabel: string;
  AppLocalEnvironmentSharePoint: string;
  AppLocalEnvironmentTeams: string;
  AppLocalEnvironmentOffice: string;
  AppLocalEnvironmentOutlook: string;
  AppSharePointEnvironment: string;
  AppTeamsTabEnvironment: string;
  AppOfficeEnvironment: string;
  AppOutlookEnvironment: string;
  UnknownEnvironment: string; 
}

myWebPart.tsx

import * as strings from 'MyWebPartStrings';

console.log(strings.Title);
console.log(strings.Description);

🔶 Warning:

Translation key "AppOutlookEnvironment" declared in mystrings.d.ts is never used in code.

🧰 SPFx Integration

In an SPFx project, localization typically lives under:

src/webparts/<your-webpart>/loc/

The plugin works automatically if your structure follows this pattern.
Just run:

npm run lint

or

eslint src --ext .ts,.tsx

🧩 Recommended Workflow

1. During development:
   • Run eslint --fix regularly to catch missing or unused localization keys early.
2. In CI/CD:
   • Add a lint step before packaging SPFx solutions:

     npm run lint

3. Before release:
   • Ensure both rules pass:
     • No extra or missing keys in translations.
     • No unused keys declared.

🔧 Advanced Options

require-used-keys accepts an optional rootDir:

"spfx-loc-checker/require-used-keys": ["warn", { "rootDir": "./src" }]

This sets the root directory for scanning code usage.

🧪 Example Commands

# Run ESLint
npx eslint src --ext .ts,.tsx

# Build plugin (if working locally)
npm run build

# Link locally for testing
npm link
npm link eslint-plugin-spfx-loc-checker

💬 Summary

| Rule | Description | Default | |------|--------------|----------| | spfx-loc-checker/match-loc-keys | Ensures .d.ts interface matches translation files | 🔴 error | | spfx-loc-checker/require-used-keys | Ensures all declared keys are used in code | 🟡 warn |

📚 License

MIT © 2025
Created with ❤️ to improve SPFx localization reliability.