{"id":15122,"library":"i18next-typescript-parser","title":"i18next TypeScript Key Extractor","description":"i18next-typescript-parser is a specialized utility library designed to accurately extract internationalization (i18n) keys from TypeScript codebases, tailored for use with the i18next framework. Unlike traditional parsers that might rely on less precise lexical analysis, this tool leverages a typed syntax tree (AST). This approach provides significantly enhanced reliability and precision in identifying translation keys within complex TypeScript structures, minimizing false positives and ensuring a more complete extraction compared to token-based methods. The current stable version is 0.3.2. As a 0.x.x series library, it is actively developed, and minor versions may introduce breaking changes. Its key differentiator is its robust, type-aware parsing mechanism, making it particularly valuable for maintaining accurate i18n key management in modern TypeScript projects.","status":"active","version":"0.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/emersion/i18next-typescript-parser","tags":["javascript","i18next","commandline","typescript"],"install":[{"cmd":"npm install i18next-typescript-parser","lang":"bash","label":"npm"},{"cmd":"yarn add i18next-typescript-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add i18next-typescript-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for parsing TypeScript code. The parser relies on TypeScript's own AST.","package":"typescript","optional":false}],"imports":[{"note":"The library primarily uses ES module syntax. CommonJS `require` is not officially supported or recommended.","wrong":"const { extractKeys } = require('i18next-typescript-parser');","symbol":"extractKeys","correct":"import { extractKeys } from 'i18next-typescript-parser';"}],"quickstart":{"code":"import { extractKeys } from 'i18next-typescript-parser';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\n// Imagine you have a directory with TypeScript files like this:\n// project-root/src/components/MyComponent.ts\n// project-root/src/utils/i18n.ts\n\n// Create a dummy TypeScript file for demonstration\nconst dummyFilePath = path.join(__dirname, 'temp_i18n_test.ts');\nfs.writeFileSync(dummyFilePath, `\n  import { useTranslation } from 'react-i18next';\n  \n  function MyComponent() {\n    const { t } = useTranslation('common');\n    console.log(t('greeting'));\n    console.log(t('welcome.message', { name: 'User' }));\n    console.log(t('nested:key.path'));\n    return <div>{t('button.label')}</div>;\n  }\n  \n  const anotherKey = t('sidebar.item');\n`);\n\n// In a real scenario, you'd configure a tsconfig.json\n// and pass it to extractKeys along with glob patterns for your source files.\n// For this example, we'll try to extract keys directly.\n\nconsole.log('Extracting i18next keys...');\nconst keys = extractKeys({\n  // For a real project, configure 'project' to point to your tsconfig.json\n  // For this example, we define a dummy project just to process the temp file\n  project: [\n    {\n      name: 'temp_project',\n      tsconfig: {\n        compilerOptions: { target: 'esnext', module: 'commonjs', lib: ['dom', 'esnext'] },\n        include: [dummyFilePath]\n      },\n      patterns: [dummyFilePath]\n    }\n  ]\n});\n\nif (keys.length === 0) {\n  console.warn('No keys extracted. Ensure your tsconfig and patterns are correct.');\n} else {\n  console.log('Extracted Keys:');\n  for (const { namespace, key } of keys) {\n    console.log(`Namespace: ${namespace || '(default)'}, Key: ${key}`);\n  }\n}\n\n// Clean up the dummy file\nfs.unlinkSync(dummyFilePath);\n","lang":"typescript","description":"This example demonstrates how to import and use `extractKeys` to find i18next translation keys within a TypeScript file."},"warnings":[{"fix":"Consult the GitHub release notes for specific breaking changes. Pin your dependency to a patch version (e.g., `~0.3.2`) to mitigate unexpected updates, and test thoroughly before deploying new versions.","message":"As a 0.x.x versioned package, `i18next-typescript-parser` does not adhere to semantic versioning strictly, meaning minor version bumps (e.g., 0.2.x to 0.3.x) may introduce breaking changes in API surface or behavior. Developers should review release notes carefully before upgrading.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Ensure your `typescript` peer dependency aligns with the versions specified in `i18next-typescript-parser`'s `package.json` (`^5 || ^6`). Upgrade or downgrade your project's `typescript` version accordingly, or consider using a tool like `npm-check-updates` to help manage peer dependency versions.","message":"The parser relies on `typescript` as a peer dependency. Mismatches between the `typescript` version installed in your project and the version expected by `i18next-typescript-parser` can lead to parsing errors or unexpected behavior. This is especially true with major TypeScript releases.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Verify that your `tsconfig.json` correctly covers all relevant TypeScript files containing i18next keys. Ensure the `patterns` array passed to `extractKeys` accurately glob-matches the files you intend to process.","message":"The precision of key extraction is highly dependent on how your `tsconfig.json` is configured and the `patterns` provided to `extractKeys`. Incorrect `include`, `exclude`, or `files` settings in `tsconfig` can result in keys not being found or unexpected files being parsed.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install TypeScript: `npm install --save-dev typescript` or `yarn add --dev typescript`.","cause":"The `typescript` package, a peer dependency, is not installed in the project.","error":"Error: Cannot find module 'typescript'"},{"fix":"Ensure your Node.js environment supports ESM (Node.js 12+ with `\"type\": \"module\"` in `package.json` or by using a bundler like Webpack/Rollup if running in browser/transpiled environment). The library is primarily designed for ESM usage.","cause":"Attempting to use the ES module `import` syntax in a CommonJS environment without proper transpilation or configuration.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Double-check the `project` configuration passed to `extractKeys`. Ensure the `tsconfig` path is correct and accessible, and that `include`/`files` arrays within your `tsconfig` correctly point to the files you want to parse.","cause":"This error often indicates that the TypeScript compiler's program object was not correctly initialized, possibly due to an invalid `tsconfig.json` path or misconfigured `project` options when calling `extractKeys`.","error":"TypeError: Cannot read properties of undefined (reading 'getSourceFile')"}],"ecosystem":"npm"}