@nkzw/eslint-plugin-fbtee 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Nakazawa Tech & Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# fbtee
+
+_**fbtee** (Far Better Translations, Extended Edition) is an internationalization framework for JavaScript & React designed to be **powerful**, **flexible**, and **intuitive**._
+
+## Why `fbtee`?
+
+- **Inline Translations for Better Developer Experience:** Embed translations directly into your code. No need to manage translation keys or wrap your code with `t()` functions. **fbtee** uses a compiler to extract strings from your code and prepare them for translation providers.
+- **Proven in Production:** Built on Facebook's `fbt`, with over a decade of production usage, serving billions of users and one year of production usage in [Athena Crisis](https://athenacrisis.com).
+- **Optimized Performance with IR:** Compiles translations into an Intermediate Representation (IR) for extracting strings, and optimizes the runtime output for performance.
+- **Easy Setup:** Quick integration with tools like Babel and Vite means you can get started instantly.
+
+## Status: Ready for Early Adopters
+
+This is a fork of Facebook's original `fbt` library, which has been archived. The aim of this fork is to create the best and most modern internationalization library for JavaScript & React.
+
+## Getting Started
+
+**fbtee** requires at least Node 22, and React 19 if you are using React.
+
+```bash
+npm install fbtee @nkzw/babel-fbtee
+```
+
+In your `vite.config.ts`:
+
+```ts
+import fbteePreset from '@nkzw/babel-fbtee';
+import react from '@vitejs/plugin-react';
+
+export default {
+  plugins: [
+    react({
+      babel: {
+        presets: [fbteePreset],
+      },
+    }),
+  ],
+};
+```
+
+**fbtee** uses three scripts to manage translations. These scripts help automate the process of collecting, creating, and compiling translations. It is recommended to add them to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "fbtee:collect": "fbtee collect --manifest < .src_manifest.json > .source_strings.json",
+    "fbtee:manifest": "fbtee manifest --src src",
+    "fbtee:translate": "fbtee translate --translations translations/*.json --jenkins > src/translations.json"
+  }
+}
+```
+
+Run these commands to set up the initial translation files:
+
+```bash
+npm run fbtee:manifest && npm run fbtee:collect && npm run fbtee:translate
+```
+
+The files generated by these commands are auto-generated and should not be checked into version control. Add the following entries to your `.gitignore`:
+
+```
+.src_manifest.json
+.source_strings.json
+.enum_manifest.json
+src/translations.json
+```
+
+Next, set up **fbtee** in your app's initialization code (e.g., `src/index.tsx`):
+
+```tsx
+import { IntlVariations, setupFbtee } from 'fbtee';
+import translations from './translations.json';
+
+setupFbtee({
+  hooks: {
+    getViewerContext: () => ({
+      GENDER: IntlVariations.GENDER_UNKNOWN,
+      locale: 'en_US',
+    }),
+  },
+  translations,
+});
+```
+
+Finally, if you are using React and TypeScript in your project, you need to add TypeScript types for **fbtee** to enable proper type checking in JSX. You can do this by referencing the `ReactTypes.d.ts` file in your main `index.tsx` file or a global type declaration file (e.g., `types.d.ts`):
+
+```tsx
+/// <reference types="fbtee/ReactTypes.d.ts" />
+```
+
+_You’re now ready to go!_
+
+## Usage
+
+_If you want to learn by example, check out the [examples](https://github.com/nkzw-tech/fbtee/tree/main/example) directory._
+
+All strings need to be wrapped by `<fbt>` (for React/JSX) or `fbt()` (for JavaScript). This ensures strings can be extracted and translated properly. The `desc` attribute is required and provides context for translators, helping them understand the intended meaning of the string.
+
+Here are some basic examples:
+
+```tsx
+const Greeting = () => <div>Hello, World!</div>;
+```
+
+You can wrap the string with `<fbt>`:
+
+```tsx
+const Greeting = () => (
+  <div>
+    <fbt desc="Greeting">Hello, World!</fbt>
+  </div>
+);
+```
+
+`<fbt>` is a special React component that marks text for translation. The `fbtee` compiler analyzes them to extract strings, and compiles them into an Intermediate Representation (IR). It supports dynamic content through <fbt:param> or even other React components. For example, if you want to greet a specific user based on a name passed as a prop, you can use `<fbt:param>`:
+
+```tsx
+const Greeting = ({ name }) => (
+  <div>
+    <fbt desc="Greeting">
+      Hello, <fbt:param name="name">{name}</fbt:param>!
+    </fbt>
+  </div>
+);
+```
+
+**fbtee** allows you to use regular React Components inside of `<fbt>` which will automatically create `<fbt:param>` calls for you:
+
+```tsx
+const Greeting = ({ name }) => (
+  <div>
+    <fbt desc="Greeting">
+      Hello, <Name name={name} />!
+    </fbt>
+  </div>
+);
+```
+
+_Note: `<fbt>` is auto-imported for you by the `@nkzw/babel-fbtee` plugin._
+
+After marking your strings for translation with `<fbt>`, run the following commands to extract, and compile translations:
+
+```bash
+npm run fbtee:collect
+```
+
+You can now upload the `.source_strings.json` file to your translation provider. Once you have the translated strings stored in a `translations/` folder as JSON files, you can run the following command to generate the translations file:
+
+```bash
+npm run fbtee:translate
+```
+
+After generating the translations file, your app is ready to display translated content in other languages.
+
+## ESLint Plugin
+
+You can install the optional eslint plugin to catch common mistakes and enforce best practices when using **fbtee**:
+
+```bash
+npm install @nkzw/eslint-plugin-fbtee
+```
+
+Add the following configuration to your ESLint configuration:
+
+```js
+{
+  extends: ['plugin:@nkzw/eslint-plugin-fbtee/strict'],
+  plugins: ['@nkzw/eslint-plugin-fbtee'],
+}
+```
+
+Or, if you'd like more granular control over the rules:
+
+```js
+{
+  plugins: ['@nkzw/eslint-plugin-fbtee'],
+  rules: {
+    '@nkzw/fbtee/no-empty-strings': 'error',
+    '@nkzw/fbtee/no-unhelpful-desc': 'error',
+  },
+}
+```
+
+## What's better about `fbtee` than `fbt`?
+
+Facebook has done an amazing job with `fbt`, an internationalization library that has been successfully used in production at Facebook for over 10 years. Their work provided a strong foundation for modern localization tools.
+
+The open-source version of `fbt`, however, became unmaintained, difficult to set up, and incompatible with modern tools. It was eventually archived in November 2024. **fbtee** builds on this foundation with several improvements:
+
+- **Easier Setup:** fbtee works with modern tools like Vite.
+- **Statically Typed:** The fbtee compiler ensures correct usage of fbtee, libary TypeScript types are provided, and an eslint plugin helps fix common mistakes.
+- **Improved React Compatibility:** Removed React-specific hacks and added support for implicit React fragments (`<>`).
+- **Enhanced Features:** Fixed and exported `intlList`, which was not functional in the original `fbt`.
+- **Modernized Codebase:** Rewritten using TypeScript, ES modules (ESM), eslint, and modern JavaScript standards. Removed cruft and legacy code.
+- **Updated Tooling:** Uses modern tools like pnpm, Vite, and esbuild for faster and more efficient development of **fbtee**.
+
+**fbtee** remains compatible with `fbt` and migration is straightforward.
+
+## Migration from `fbt`:
+
+**fbtee** is compatible with `fbt`. If you are already using `fbt`, migrating to fbtee is straightforward:
+
+- Follow the "Getting Started" guide above and remove all "fbt" related packages.
+- Make sure you are using React 19.
+- Replace `import { fbt } from 'fbt'` with `import { fbt } from 'fbtee'`.
+- Rename commands from `fbt-collect`, `fbt-manifest` and `fbt-translate` to `fbtee-collect`, `fbtee-manifest` and `fbtee-translate`.
+- If you were using CommonJS modules for common strings or enums, convert them to ES modules.
+- Ensure you are using the latest version of Node.js 22 or later.
+- Rename your `init({})` call to `setupFbtee({})`.
+
+After these changes, your project should work seamlessly with **fbtee**.
+
+_Note: Some legacy behavior and options were removed from `fbtee`. If you have a complex setup, please consider [reaching out to us for help](mailto:fbtee@nakazawa.dev)._
+
+## Credits
+
+- `fbt` was originally created by [Facebook](https://github.com/facebook/fbt).
+- The auto-import plugin was created by [@alexandernanberg](https://github.com/alexandernanberg).
+- [Nakazawa Tech](https://nkzw.tech) rewrote `fbt` into `fbtee` and continues to maintain this project.
+
+## Support
+
+- Check out the [#fbtee channel on Reactiflux's Discord server](https://discord.gg/reactiflux).

package/docs/rules/no-empty-strings.md

@@ -0,0 +1,29 @@
+# Prevent empty strings from being given to `<fbt>` or `fbt()` (fbtee/no-empty-strings)
+
+## Rule Details
+
+This rule ensures that `<fbt>` tags and `fbt()`/`fbs()` calls are given meaningful text.
+
+Examples of **incorrect** code for this rule:
+
+```jsx
+<fbt desc="Greeting"></fbt>
+```
+
+```jsx
+<fbt desc="Greeting">{''}</fbt>
+```
+
+```jsx
+fbt('', 'Greeting');
+```
+
+Examples of **correct** code for this rule:
+
+```jsx
+<fbt desc="Greeting">Hello</fbt>
+```
+
+```jsx
+fbt('Hello', 'Greeting');
+```

package/docs/rules/no-unhelpful-desc.md

@@ -0,0 +1,41 @@
+# Prevent unhelpful descriptions being given to `<fbt>` or `fbt()` (fbtee/no-unhelpful-desc)
+
+## Rule Details
+
+This rule enforces that meaningful and non-empty descriptions are provided to <fbt> elements and fbt()/fbs() function calls. Descriptions (desc) are crucial for ensuring proper translation context and avoiding ambiguous or unhelpful translations.
+
+Examples of **incorrect** code for this rule:
+
+```jsx
+<fbt desc="">Hello world</fbt>
+```
+
+```jsx
+<fbt desc="foo">Hello world</fbt>
+```
+
+```jsx
+<fbt desc="Hello world">Hello world</fbt>
+```
+
+```jsx
+fbt('Hello world', '');
+```
+
+```jsx
+fbt('Hello world', 'foo');
+```
+
+```jsx
+fbt('Hello world', 'hello world');
+```
+
+Examples of **correct** code for this rule:
+
+```jsx
+<fbt desc="Greeting">Hello</fbt>
+```
+
+```jsx
+fbt('Hello', 'Greeting');
+```

package/lib/index.cjs

@@ -0,0 +1,313 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var src_exports = {};
+__export(src_exports, {
+  configs: () => configs,
+  meta: () => meta,
+  rules: () => rules
+});
+module.exports = __toCommonJS(src_exports);
+
+// package.json
+var package_default = {
+  name: "@nkzw/eslint-plugin-fbtee",
+  version: "0.0.1",
+  description: "",
+  keywords: [],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/nkzw-tech/fbtee.git",
+    directory: "packages/eslint-plugin-fbtee"
+  },
+  license: "MIT",
+  type: "module",
+  exports: {
+    import: "./lib/index.js",
+    require: "./lib/index.cjs"
+  },
+  scripts: {
+    build: "tsup src/index.tsx -d lib --target=node22 --format=esm,cjs --clean --no-splitting --dts"
+  },
+  dependencies: {
+    "@typescript-eslint/utils": "^8.18.0"
+  },
+  devDependencies: {
+    "@typescript-eslint/rule-tester": "^8.18.0"
+  }
+};
+
+// src/utils.tsx
+var import_utils = require("@typescript-eslint/utils");
+var createRule = import_utils.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/nkzw-tech/fbtee/tree/main/packages/eslint-plugin-fbt/docs/rules/${name}`
+);
+function resolveMemberExpressions(object, property) {
+  if (object.type === "JSXMemberExpression") {
+    return `${resolveMemberExpressions(object.object, object.property)}.${property.name}`;
+  }
+  return `${object.name}.${property.name}`;
+}
+function elementType(node) {
+  if (node.type === "JSXFragment") {
+    return "<>";
+  }
+  const { name } = node.openingElement;
+  switch (name.type) {
+    case "JSXIdentifier": {
+      return name.name;
+    }
+    case "JSXMemberExpression": {
+      const { object, property } = name;
+      return resolveMemberExpressions(object, property);
+    }
+    case "JSXNamespacedName": {
+      return `${name.namespace.name}:${name.name.name}`;
+    }
+    default: {
+      throw new Error("Unsupported JSX node type.");
+    }
+  }
+}
+function resolveJsxElementTextContent(node) {
+  return node.children.map((child) => {
+    if (child.type === "JSXText") {
+      return child.value.trim();
+    }
+    if (child.type === "JSXExpressionContainer") {
+      return resolveNodeValue(child.expression) || "";
+    }
+    return "";
+  }).join("").trim();
+}
+function resolveBinaryExpression(node) {
+  if (node.operator !== "+") {
+    return null;
+  }
+  const leftValue = resolveNodeValue(node.left);
+  const rightValue = resolveNodeValue(node.right);
+  if (leftValue !== null && rightValue !== null) {
+    return leftValue + rightValue;
+  }
+  return null;
+}
+function resolveNodeValue(node) {
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value;
+  }
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+    return node.quasis.map((quasi) => quasi.value.raw).join("");
+  }
+  if (node.type === "BinaryExpression") {
+    return resolveBinaryExpression(node);
+  }
+  if (node.type === "JSXExpressionContainer") {
+    return resolveNodeValue(node.expression);
+  }
+  return null;
+}
+
+// src/rules/no-empty-strings.tsx
+var no_empty_strings_default = createRule({
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type === "Identifier" && !(node.callee.name === "fbt" || node.callee.name === "fbs")) {
+          return;
+        }
+        const [text] = node.arguments;
+        if (text && text.type !== "SpreadElement" && isEmptyString(text)) {
+          context.report({
+            messageId: "emptyString",
+            node: text
+          });
+        }
+      },
+      JSXElement(node) {
+        if (elementType(node) !== "fbt") {
+          return;
+        }
+        const nodesToReport = /* @__PURE__ */ new Set();
+        const hasTextContent = validateChildren(node, nodesToReport);
+        if (!hasTextContent) {
+          for (const node2 of nodesToReport) {
+            context.report({
+              messageId: "jsxEmptyString",
+              node: node2
+            });
+          }
+        }
+      }
+    };
+  },
+  defaultOptions: [],
+  meta: {
+    docs: {
+      description: "Disallow empty strings in fbt elements or function calls."
+    },
+    messages: {
+      emptyString: "Empty strings are not allowed in fbt() or fbs() function arguments.",
+      jsxEmptyString: "Empty strings are not allowed as children of <fbt> tags."
+    },
+    schema: [],
+    type: "problem"
+  },
+  name: "no-empty-strings"
+});
+function validateChildren(node, nodesToReport) {
+  let hasTextContent = false;
+  for (const child of node.children) {
+    if (child.type === "JSXText" && node.children.length === 1) {
+      if (child.value.trim() === "") {
+        nodesToReport.add(child);
+      } else {
+        hasTextContent = true;
+      }
+    }
+    if (child.type === "JSXExpressionContainer" && child.expression.type !== "JSXEmptyExpression") {
+      if (isEmptyString(child.expression)) {
+        nodesToReport.add(child.expression);
+      } else {
+        hasTextContent = true;
+      }
+    }
+    if (child.type === "JSXElement" || child.type === "JSXFragment") {
+      hasTextContent ||= validateChildren(child, nodesToReport);
+    }
+    if (hasTextContent) {
+      break;
+    }
+  }
+  if (!hasTextContent && nodesToReport.size === 0) {
+    nodesToReport.add(node);
+  }
+  return hasTextContent;
+}
+function isEmptyString(node) {
+  return resolveNodeValue(node)?.trim() === "";
+}
+
+// src/rules/no-unhelpful-desc.tsx
+var no_unhelpful_desc_default = createRule({
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || !(node.callee.name === "fbt" || node.callee.name === "fbs")) {
+          return;
+        }
+        const [textArg, descArg] = node.arguments;
+        const desc = descArg && descArg.type !== "SpreadElement" ? resolveNodeValue(descArg)?.trim() : null;
+        if (!desc) {
+          context.report({
+            messageId: "emptyDesc",
+            node: descArg || node
+          });
+          return;
+        }
+        if (desc.length <= 4) {
+          context.report({
+            messageId: "shortDesc",
+            node: descArg || node
+          });
+          return;
+        }
+        const text = textArg && textArg.type !== "SpreadElement" ? resolveNodeValue(textArg)?.trim() : null;
+        if (desc.toLowerCase() === text?.toLowerCase()) {
+          context.report({
+            messageId: "duplicateDesc",
+            node: descArg || node
+          });
+        }
+      },
+      JSXAttribute(node) {
+        if (elementType(node.parent.parent) !== "fbt") {
+          return;
+        }
+        if (node.name.name !== "desc" || !node.value) {
+          return;
+        }
+        if (node.value.type === "JSXExpressionContainer" && (node.value.expression.type === "Identifier" || node.value.expression.type === "CallExpression")) {
+          return;
+        }
+        const desc = resolveNodeValue(node.value)?.trim();
+        if (!desc) {
+          context.report({
+            messageId: "jsxEmptyDesc",
+            node: node.value
+          });
+          return;
+        }
+        if (desc.length <= 4) {
+          context.report({
+            messageId: "shortDesc",
+            node: node.value
+          });
+          return;
+        }
+        const textContent = resolveJsxElementTextContent(node.parent.parent);
+        if (desc.toLowerCase() === textContent.toLowerCase()) {
+          context.report({
+            messageId: "duplicateDesc",
+            node: node.value
+          });
+        }
+      }
+    };
+  },
+  defaultOptions: [],
+  meta: {
+    docs: {
+      description: "Enforce meaningful and non-empty descriptions in <fbt> elements and fbt()/fbs() function calls."
+    },
+    messages: {
+      duplicateDesc: 'The "desc" attribute or argument should not be a duplicate of the text content.',
+      emptyDesc: 'The "desc" argument in fbt() and fbs() must not be empty.',
+      jsxEmptyDesc: 'The "desc" attribute in <fbt> must not be empty.',
+      shortDesc: 'The "desc" attribute or argument is too short. Use a more descriptive and meaningful explanation.'
+    },
+    schema: [],
+    type: "problem"
+  },
+  name: "no-unhelpful-desc"
+});
+
+// src/index.tsx
+var meta = {
+  name: package_default.name,
+  version: package_default.version
+};
+var rules = {
+  "no-empty-strings": no_empty_strings_default,
+  "no-unhelpful-desc": no_unhelpful_desc_default
+};
+var configs = {
+  strict: {
+    rules: {
+      "@nkzw/fbtee/no-empty-strings": 2,
+      "@nkzw/fbtee/no-unhelpful-desc": 2
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  configs,
+  meta,
+  rules
+});

package/lib/index.d.cts

@@ -0,0 +1,20 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+
+declare const meta: {
+    name: string;
+    version: string;
+};
+declare const rules: {
+    'no-empty-strings': _typescript_eslint_utils_ts_eslint.RuleModule<"emptyString" | "jsxEmptyString", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener>;
+    'no-unhelpful-desc': _typescript_eslint_utils_ts_eslint.RuleModule<"emptyDesc" | "jsxEmptyDesc" | "duplicateDesc" | "shortDesc", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener>;
+};
+declare const configs: {
+    strict: {
+        rules: {
+            '@nkzw/fbtee/no-empty-strings': number;
+            '@nkzw/fbtee/no-unhelpful-desc': number;
+        };
+    };
+};
+
+export { configs, meta, rules };

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+
+declare const meta: {
+    name: string;
+    version: string;
+};
+declare const rules: {
+    'no-empty-strings': _typescript_eslint_utils_ts_eslint.RuleModule<"emptyString" | "jsxEmptyString", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener>;
+    'no-unhelpful-desc': _typescript_eslint_utils_ts_eslint.RuleModule<"emptyDesc" | "jsxEmptyDesc" | "duplicateDesc" | "shortDesc", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener>;
+};
+declare const configs: {
+    strict: {
+        rules: {
+            '@nkzw/fbtee/no-empty-strings': number;
+            '@nkzw/fbtee/no-unhelpful-desc': number;
+        };
+    };
+};
+
+export { configs, meta, rules };