@grafana/create-plugin 6.3.0-canary.2320.19638409321.0 → 6.3.0

package/src/codemods/additions/scripts/i18n/README.md

@@ -1,157 +0,0 @@
-# I18n Addition
-
-Adds internationalization (i18n) support to a Grafana plugin.
-
-## Usage
-
-```bash
-npx @grafana/create-plugin add i18n --locales <locales>
-```
-
-## Required Flags
-
-### `--locales`
-
-A comma-separated list of locale codes to support in your plugin.
-
-**Format:** Locale codes must follow the `xx-XX` pattern (e.g., `en-US`, `es-ES`, `sv-SE`)
-
-**Example:**
-
-```bash
-npx @grafana/create-plugin add i18n --locales en-US,es-ES,sv-SE
-```
-
-## What This Addition Does
-
-This addition configures your plugin for internationalization by:
-
-1. **Updating `docker-compose.yaml`** - Adds the `localizationForPlugins` feature toggle to your local Grafana instance
-2. **Updating `src/plugin.json`** - Adds the `languages` array and updates `grafanaDependency`
-3. **Creating locale files** - Creates empty JSON files for each locale at `src/locales/{locale}/{pluginId}.json`
-4. **Adding dependencies** - Installs `@grafana/i18n` and optionally `semver` (for backward compatibility)
-5. **Updating ESLint config** - Adds i18n linting rules to catch untranslated strings
-6. **Initializing i18n in module.ts** - Adds `initPluginTranslations()` call to your plugin's entry point
-7. **Creating support files**:
-   - `i18next.config.ts` - Configuration for extracting translations
-   - `src/loadResources.ts` - (Only for Grafana < 12.1.0) Custom resource loader
-8. **Adding npm scripts** - Adds `i18n-extract` script to extract translations from your code
-
-## Backward Compatibility
-
-The addition automatically detects your plugin's `grafanaDependency` version:
-
-### Grafana >= 12.1.0 (Modern)
-
-- Sets `grafanaDependency` to `>=12.1.0`
-- Grafana handles loading translations automatically
-- Simple initialization: `await initPluginTranslations(pluginJson.id)`
-- No `loadResources.ts` file needed
-- No `semver` dependency needed
-
-### Grafana 11.0.0 - 12.0.x (Backward Compatible)
-
-- Keeps or sets `grafanaDependency` to `>=11.0.0`
-- Plugin handles loading translations
-- Creates `src/loadResources.ts` for custom resource loading
-- Adds runtime version check using `semver`
-- Initialization with loaders: `await initPluginTranslations(pluginJson.id, loaders)`
-
-## Running Multiple Times (Idempotent)
-
-This addition is **defensive** and can be run multiple times safely. Each operation checks if it's already been done:
-
-### Adding New Locales
-
-You can run the command again with additional locales to add them:
-
-```bash
-# First run
-npx @grafana/create-plugin add i18n --locales en-US
-
-# Later, add more locales
-npx @grafana/create-plugin add i18n --locales en-US,es-ES,sv-SE
-```
-
-The addition will:
-
-- ✅ Merge new locales into `plugin.json` without duplicates
-- ✅ Create only the new locale files (won't overwrite existing ones)
-- ✅ Skip updating files that already have i18n configured
-
-### What Won't Be Duplicated
-
-- **Locale files**: Existing locale JSON files are never overwritten (preserves your translations)
-- **Dependencies**: Won't re-add dependencies that already exist
-- **ESLint config**: Won't duplicate the i18n plugin import or rules
-- **Module initialization**: Won't add `initPluginTranslations` if it's already present
-- **Support files**: Won't overwrite `i18next.config.ts` or `loadResources.ts` if they exist
-- **npm scripts**: Won't overwrite the `i18n-extract` script if it exists
-- **Docker feature toggle**: Won't duplicate the feature toggle
-
-## Files Created
-
-```
-your-plugin/
-├── docker-compose.yaml              # Modified: adds localizationForPlugins toggle
-├── src/
-│   ├── plugin.json                  # Modified: adds languages array
-│   ├── module.ts                    # Modified: adds i18n initialization
-│   ├── loadResources.ts            # Created: (Grafana 11.x only) resource loader
-│   └── locales/
-│       ├── en-US/
-│       │   └── your-plugin-id.json # Created: empty translation file
-│       ├── es-ES/
-│       │   └── your-plugin-id.json # Created: empty translation file
-│       └── sv-SE/
-│           └── your-plugin-id.json # Created: empty translation file
-├── i18next.config.ts                # Created: extraction config
-├── eslint.config.mjs                # Modified: adds i18n linting rules
-└── package.json                     # Modified: adds dependencies and scripts
-```
-
-## Dependencies Added
-
-**Always:**
-
-- `@grafana/i18n` (v12.2.2) - i18n utilities and types
-- `i18next-cli` (dev) - Translation extraction tool
-
-**For Grafana 11.x only:**
-
-- `semver` - Runtime version checking
-- `@types/semver` (dev) - TypeScript types for semver
-
-## Next Steps
-
-After running this addition:
-
-1. **Extract translations**: Run `npm run i18n-extract` to scan your code for translatable strings
-2. **Add translations**: Fill in your locale JSON files with translated strings
-3. **Use in code**: Import and use the translation functions:
-
-   ```typescript
-   import { t, Trans } from '@grafana/i18n';
-
-   // Use t() for simple strings
-   const title = t('components.myComponent.title', 'Default Title');
-
-   // Use Trans for JSX
-   <Trans i18nKey="components.myComponent.description">
-     This is a description
-   </Trans>
-   ```
-
-## Debug Output
-
-Enable debug logging to see what the addition is doing:
-
-```bash
-DEBUG=create-plugin:additions npx @grafana/create-plugin add i18n --locales en-US,es-ES
-```
-
-## References
-
-- [Grafana i18n Documentation](https://grafana.com/developers/plugin-tools/how-to-guides/plugin-internationalization)
-- [Grafana 11.x i18n Documentation](https://grafana.com/developers/plugin-tools/how-to-guides/plugin-internationalization-grafana-11)
-- [Available Languages](https://github.com/grafana/grafana/blob/main/packages/grafana-i18n/src/constants.ts)

package/src/codemods/additions/scripts/i18n/code-generation.ts

@@ -1,156 +0,0 @@
-import * as recast from 'recast';
-import * as babelParser from 'recast/parsers/babel-ts.js';
-
-import type { Context } from '../../../context.js';
-import { additionsDebug } from '../../../utils.js';
-
-const { builders } = recast.types;
-
-export function addI18nInitialization(context: Context, needsBackwardCompatibility: boolean): void {
-  // Find module.ts or module.tsx
-  const moduleTsPath = context.doesFileExist('src/module.ts')
-    ? 'src/module.ts'
-    : context.doesFileExist('src/module.tsx')
-      ? 'src/module.tsx'
-      : null;
-
-  if (!moduleTsPath) {
-    additionsDebug('No module.ts or module.tsx found, skipping i18n initialization');
-    return;
-  }
-
-  const moduleContent = context.getFile(moduleTsPath);
-  if (!moduleContent) {
-    return;
-  }
-
-  // Defensive: check if i18n is already initialized
-  if (moduleContent.includes('initPluginTranslations')) {
-    additionsDebug('i18n already initialized in module file');
-    return;
-  }
-
-  try {
-    const ast = recast.parse(moduleContent, {
-      parser: babelParser,
-    });
-
-    const imports = [];
-
-    // Add necessary imports based on backward compatibility
-    imports.push(
-      builders.importDeclaration(
-        [builders.importSpecifier(builders.identifier('initPluginTranslations'))],
-        builders.literal('@grafana/i18n')
-      )
-    );
-
-    imports.push(
-      builders.importDeclaration(
-        [builders.importDefaultSpecifier(builders.identifier('pluginJson'))],
-        builders.literal('plugin.json')
-      )
-    );
-
-    if (needsBackwardCompatibility) {
-      imports.push(
-        builders.importDeclaration(
-          [builders.importSpecifier(builders.identifier('config'))],
-          builders.literal('@grafana/runtime')
-        )
-      );
-      imports.push(
-        builders.importDeclaration(
-          [builders.importDefaultSpecifier(builders.identifier('semver'))],
-          builders.literal('semver')
-        )
-      );
-      imports.push(
-        builders.importDeclaration(
-          [builders.importSpecifier(builders.identifier('loadResources'))],
-          builders.literal('./loadResources')
-        )
-      );
-    }
-
-    // Add imports after the first import statement
-    const firstImportIndex = ast.program.body.findIndex((node: any) => node.type === 'ImportDeclaration');
-    if (firstImportIndex !== -1) {
-      ast.program.body.splice(firstImportIndex + 1, 0, ...imports);
-    } else {
-      ast.program.body.unshift(...imports);
-    }
-
-    // Add i18n initialization code
-    const i18nInitCode = needsBackwardCompatibility
-      ? `// Before Grafana version 12.1.0 the plugin is responsible for loading translation resources
-// In Grafana version 12.1.0 and later Grafana is responsible for loading translation resources
-const loaders = semver.lt(config?.buildInfo?.version, '12.1.0') ? [loadResources] : [];
-
-await initPluginTranslations(pluginJson.id, loaders);`
-      : `await initPluginTranslations(pluginJson.id);`;
-
-    // Parse the initialization code and insert it at the top level (after imports)
-    const initAst = recast.parse(i18nInitCode, {
-      parser: babelParser,
-    });
-
-    // Find the last import index
-    const lastImportIndex = ast.program.body.findLastIndex((node: any) => node.type === 'ImportDeclaration');
-    if (lastImportIndex !== -1) {
-      ast.program.body.splice(lastImportIndex + 1, 0, ...initAst.program.body);
-    } else {
-      ast.program.body.unshift(...initAst.program.body);
-    }
-
-    const output = recast.print(ast, {
-      tabWidth: 2,
-      trailingComma: true,
-      lineTerminator: '\n',
-    }).code;
-
-    context.updateFile(moduleTsPath, output);
-    additionsDebug(`Updated ${moduleTsPath} with i18n initialization`);
-  } catch (error) {
-    additionsDebug('Error updating module file:', error);
-  }
-}
-
-export function createLoadResourcesFile(context: Context): void {
-  const loadResourcesPath = 'src/loadResources.ts';
-
-  // Defensive: skip if already exists
-  if (context.doesFileExist(loadResourcesPath)) {
-    additionsDebug('loadResources.ts already exists, skipping');
-    return;
-  }
-
-  const pluginJsonRaw = context.getFile('src/plugin.json');
-  if (!pluginJsonRaw) {
-    additionsDebug('Cannot create loadResources.ts without plugin.json');
-    return;
-  }
-
-  const loadResourcesContent = `import { LANGUAGES, ResourceLoader, Resources } from '@grafana/i18n';
-import pluginJson from 'plugin.json';
-
-const resources = LANGUAGES.reduce<Record<string, () => Promise<{ default: Resources }>>>((acc, lang) => {
-  acc[lang.code] = async () => await import(\`./locales/\${lang.code}/\${pluginJson.id}.json\`);
-  return acc;
-}, {});
-
-export const loadResources: ResourceLoader = async (resolvedLanguage: string) => {
-  try {
-    const translation = await resources[resolvedLanguage]();
-    return translation.default;
-  } catch (error) {
-    // This makes sure that the plugin doesn't crash when the resolved language in Grafana isn't supported by the plugin
-    console.error(\`The plugin '\${pluginJson.id}' doesn't support the language '\${resolvedLanguage}'\`, error);
-    return {};
-  }
-};
-`;
-
-  context.addFile(loadResourcesPath, loadResourcesContent);
-  additionsDebug('Created src/loadResources.ts for backward compatibility');
-}

package/src/codemods/additions/scripts/i18n/config-updates.ts

@@ -1,139 +0,0 @@
-import { coerce, gte } from 'semver';
-import { parseDocument, stringify } from 'yaml';
-
-import type { Context } from '../../../context.js';
-import { additionsDebug } from '../../../utils.js';
-
-export function updateDockerCompose(context: Context): void {
-  if (!context.doesFileExist('docker-compose.yaml')) {
-    additionsDebug('docker-compose.yaml not found, skipping');
-    return;
-  }
-
-  const composeContent = context.getFile('docker-compose.yaml');
-  if (!composeContent) {
-    return;
-  }
-
-  try {
-    const composeDoc = parseDocument(composeContent);
-    const currentEnv = composeDoc.getIn(['services', 'grafana', 'environment']);
-
-    if (!currentEnv) {
-      additionsDebug('No environment section found in docker-compose.yaml, skipping');
-      return;
-    }
-
-    // Check if the feature toggle is already set
-    if (typeof currentEnv === 'object') {
-      const envMap = currentEnv as any;
-      const toggleValue = envMap.get('GF_FEATURE_TOGGLES_ENABLE');
-
-      if (toggleValue) {
-        const toggleStr = toggleValue.toString();
-        if (toggleStr.includes('localizationForPlugins')) {
-          additionsDebug('localizationForPlugins already in GF_FEATURE_TOGGLES_ENABLE');
-          return;
-        }
-        // Append to existing feature toggles
-        composeDoc.setIn(
-          ['services', 'grafana', 'environment', 'GF_FEATURE_TOGGLES_ENABLE'],
-          `${toggleStr},localizationForPlugins`
-        );
-      } else {
-        // Set new feature toggle
-        composeDoc.setIn(['services', 'grafana', 'environment', 'GF_FEATURE_TOGGLES_ENABLE'], 'localizationForPlugins');
-      }
-
-      context.updateFile('docker-compose.yaml', stringify(composeDoc));
-      additionsDebug('Updated docker-compose.yaml with localizationForPlugins feature toggle');
-    }
-  } catch (error) {
-    additionsDebug('Error updating docker-compose.yaml:', error);
-  }
-}
-
-export function updatePluginJson(context: Context, locales: string[], needsBackwardCompatibility: boolean): void {
-  if (!context.doesFileExist('src/plugin.json')) {
-    additionsDebug('src/plugin.json not found, skipping');
-    return;
-  }
-
-  const pluginJsonRaw = context.getFile('src/plugin.json');
-  if (!pluginJsonRaw) {
-    return;
-  }
-
-  try {
-    const pluginJson = JSON.parse(pluginJsonRaw);
-
-    // Merge locales with existing languages (defensive: avoid duplicates)
-    const existingLanguages = Array.isArray(pluginJson.languages) ? pluginJson.languages : [];
-    const mergedLanguages = [...new Set([...existingLanguages, ...locales])];
-    pluginJson.languages = mergedLanguages;
-
-    // Update grafanaDependency based on backward compatibility needs
-    if (!pluginJson.dependencies) {
-      pluginJson.dependencies = {};
-    }
-
-    const currentGrafanaDep = pluginJson.dependencies.grafanaDependency || '>=11.0.0';
-    const targetVersion = needsBackwardCompatibility ? '11.0.0' : '12.1.0';
-    const minVersion = coerce(targetVersion);
-    const currentVersion = coerce(currentGrafanaDep.replace(/^[><=]+/, ''));
-
-    if (!currentVersion || !minVersion || !gte(currentVersion, minVersion)) {
-      pluginJson.dependencies.grafanaDependency = `>=${targetVersion}`;
-      additionsDebug(`Updated grafanaDependency to >=${targetVersion}`);
-    }
-
-    context.updateFile('src/plugin.json', JSON.stringify(pluginJson, null, 2));
-    additionsDebug('Updated src/plugin.json with languages:', locales);
-  } catch (error) {
-    additionsDebug('Error updating src/plugin.json:', error);
-  }
-}
-
-export function createI18nextConfig(context: Context): void {
-  // Defensive: skip if already exists
-  if (context.doesFileExist('i18next.config.ts')) {
-    additionsDebug('i18next.config.ts already exists, skipping');
-    return;
-  }
-
-  const pluginJsonRaw = context.getFile('src/plugin.json');
-  if (!pluginJsonRaw) {
-    additionsDebug('Cannot create i18next.config.ts without plugin.json');
-    return;
-  }
-
-  try {
-    const pluginJson = JSON.parse(pluginJsonRaw);
-    const pluginId = pluginJson.id;
-
-    if (!pluginId) {
-      additionsDebug('No plugin ID found in plugin.json');
-      return;
-    }
-
-    const i18nextConfig = `import { defineConfig } from 'i18next-cli';
-import pluginJson from './src/plugin.json';
-
-export default defineConfig({
-  locales: pluginJson.languages,
-  extract: {
-    input: ['src/**/*.{tsx,ts}'],
-    output: 'src/locales/{{language}}/{{namespace}}.json',
-    defaultNS: pluginJson.id,
-    functions: ['t', '*.t'],
-    transComponents: ['Trans'],
-  },
-});
-`;
-
-    context.addFile('i18next.config.ts', i18nextConfig);
-    additionsDebug('Created i18next.config.ts');
-  } catch (error) {
-    additionsDebug('Error creating i18next.config.ts:', error);
-  }
-}