@atlaskit/ads-mcp 1.10.2 → 1.10.3

package/dist/es2019/tools/i18n-conversion/guide.js

@@ -5,8 +5,8 @@
 export const i18nConversionGuide = {
   id: 'hardcoded-string-to-formatmessage',
   title: 'Hardcoded String to formatMessage Conversion Guide',
-  description: 'Comprehensive guide for converting hardcoded strings to use formatMessage or FormattedMessage from @atlassian/jira-intl or react-intl',
-  purpose: 'This guide instructs LLM agents to convert hardcoded strings to use formatMessage or FormattedMessage. The import source depends on the file path: use @atlassian/jira-intl for Jira files (path contains "jira"), and react-intl for any non-Jira files. **CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, reuse that import. If the file already uses FormattedMessage, use FormattedMessage for consistency instead of useIntl + formatMessage. The goal is to find all hardcoded strings in JSX and convert them to internationalized messages.',
+  description: 'Comprehensive guide for converting hardcoded strings to use formatMessage or FormattedMessage from @jira/platform__react-intl or react-intl',
+  purpose: 'This guide instructs LLM agents to convert hardcoded strings to use formatMessage or FormattedMessage. The import source depends on the file path: use @jira/platform__react-intl for Jira files (path contains "jira"), and react-intl for any non-Jira files. **CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, reuse that import. If the file already uses FormattedMessage, use FormattedMessage for consistency instead of useIntl + formatMessage. The goal is to find all hardcoded strings in JSX and convert them to internationalized messages.',
   scope: `**CRITICAL SCOPE**: This process should **ONLY** focus on converting hardcoded strings (literal strings in JSX, eslint-disable comments for no-literal-string-in-jsx, etc.) to use formatMessage. Do NOT modify pre-existing messages that were already in the codebase, even if they have poor descriptions, incorrect placeholder names, or other quality issues. Only convert NEW hardcoded strings.
 
 **PATH SCOPE LIMITATION**: If a specific file, package name, or path is provided, **ONLY** find and convert hardcoded strings within that specified path. Do NOT modify files outside the provided scope.
@@ -16,14 +16,14 @@ export const i18nConversionGuide = {
 **CRITICAL: FIX ALL VIOLATIONS IN FILE**: When a specific file is mentioned (even with line numbers like \`@file.tsx:139-142\`), you MUST find and fix **ALL** @atlassian/i18n/no-literal-string-in-jsx violations in that entire file, not just the specific lines mentioned. Scan the entire file for hardcoded strings WITH eslint-disable comments and convert them all. The line numbers are just a reference point - the goal is to fix all i18n violations (those with eslint-disable comments) in the provided file.
 
 **CRITICAL: STRING FILTERING**: When finding eslint-disable comments, you MUST examine the actual string content. Only convert strings that contain **user-facing English text**. Many English strings are technical/non-user-facing and should NOT be converted (e.g., product names like "Jira", URLs like "https://example.com", technical IDs, symbols). Use the ESLint ignore patterns to identify which English strings to skip - strings matching ignore patterns should be LEFT AS-IS with their eslint-disable comments intact.`,
-  implementationChecklist: ['**CRITICAL: Only convert strings with eslint-disable** - ONLY convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT convert strings without these comments (e.g., field labels like label="Space Name" without eslint-disable should remain as-is).', '**CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, REUSE that import. Only add a new import if none exists.', '**CRITICAL: Match existing pattern** - If the file already uses FormattedMessage, use FormattedMessage with inline props. If it uses useIntl + formatMessage, use defineMessage + formatMessage. Match the existing code style.', "**CRITICAL: When to use formatMessage() vs <FormattedMessage>** - Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}.", 'Import: Use "@atlassian/jira-intl" for Jira files or "react-intl" for non-Jira files. Note: "react-intl" and "react-intl" are treated the same way - both use the same API. When adding to existing imports, maintain alphabetical order: import { defineMessage, FormattedMessage } from "react-intl";', '**CRITICAL: FormattedMessage pattern** - When using FormattedMessage, define message details directly inline: <FormattedMessage id="..." defaultMessage="..." description="..." />. NO need to use defineMessage - FormattedMessage accepts these props directly.', '**CRITICAL: formatMessage pattern** - When using useIntl + formatMessage, create message constants using defineMessage (singular) at the top of the file - use defineMessage for each individual message, NOT defineMessages. Then use: const { formatMessage } = useIntl(); formatMessage(messageKey)', '**CRITICAL: i18n ID Format**: For files in `/next/packages/`, i18n ids MUST start with the package name (with dashes). Format: `{package-name}.{component-or-feature}.{message-key}`. Example: For package `comment-extension-handlers`, use `comment-extension-handlers.legacy-content-modal.close-button`. For package `rovo-ai-search`, use `rovo-ai-search.view-profile-text` or `rovo-ai-search.knowledge-cards.copy-email-address`.', '**CRITICAL: ai-non-final Suffix**: ALL new message IDs MUST end with `.ai-non-final` suffix. This applies to ALL newly created messages, regardless of whether existing messages in the file have this suffix. Format: `{message-key}.ai-non-final`. Example: `applinks.administration.list.applinks-table.system-label.ai-non-final`. This suffix indicates the message is AI-generated and may need review before finalization.', 'Replace hardcoded strings with either formatMessage(messageKey) or <FormattedMessage id="..." defaultMessage="..." description="..." /> based on existing pattern', '**CRITICAL: Write comprehensive descriptions** - Descriptions are instructions for translators. Include: (1) Where text is shown and the UI element (e.g., "on a button", "as an error message", "as a title", "for a link", "as a drop-down item"), (2) What it does, triggers, or prompts, (3) If there is a placeholder, explain how it will be substituted and with what, (4) If there is an ICU MessageFormat statement (not a placeholder!), provide instruction on the resolved ICU message, not on the ICU structure unless there are more than 2 plural statements, (5) Explain the purpose of the sentence in defaultMessage, (6) Propose an alternative text in Plain English only if the text contains an idiom. Descriptions must be 40+ chars and unique from defaultMessage.', 'Remove eslint-disable for no-literal-string-in-jsx ONLY after converting', '**VERIFICATION**: To verify all hardcoded strings are fixed, search for `@atlassian/i18n/no-literal-string-in-jsx` in the file. Do NOT run eslint - just search for the eslint-disable comments. If no matches are found, all hardcoded strings have been converted.'],
+  implementationChecklist: ['**CRITICAL: Only convert strings with eslint-disable** - ONLY convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT convert strings without these comments (e.g., field labels like label="Space Name" without eslint-disable should remain as-is).', '**CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, REUSE that import. Only add a new import if none exists.', '**CRITICAL: Match existing pattern** - If the file already uses FormattedMessage, use FormattedMessage with inline props. If it uses useIntl + formatMessage, use defineMessage + formatMessage. Match the existing code style.', "**CRITICAL: When to use formatMessage() vs <FormattedMessage>** - Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}.", 'Import: Use "@jira/platform__react-intl" for Jira files or "react-intl" for non-Jira files. Note: "react-intl" and "react-intl" are treated the same way - both use the same API. When adding to existing imports, maintain alphabetical order: import { defineMessage, FormattedMessage } from "react-intl";', '**CRITICAL: FormattedMessage pattern** - When using FormattedMessage, define message details directly inline: <FormattedMessage id="..." defaultMessage="..." description="..." />. NO need to use defineMessage - FormattedMessage accepts these props directly.', '**CRITICAL: formatMessage pattern** - When using useIntl + formatMessage, create message constants using defineMessage (singular) at the top of the file - use defineMessage for each individual message, NOT defineMessages. Then use: const { formatMessage } = useIntl(); formatMessage(messageKey)', '**CRITICAL: i18n ID Format**: For files in `/next/packages/`, i18n ids MUST start with the package name (with dashes). Format: `{package-name}.{component-or-feature}.{message-key}`. Example: For package `comment-extension-handlers`, use `comment-extension-handlers.legacy-content-modal.close-button`. For package `rovo-ai-search`, use `rovo-ai-search.view-profile-text` or `rovo-ai-search.knowledge-cards.copy-email-address`.', '**CRITICAL: ai-non-final Suffix**: ALL new message IDs MUST end with `.ai-non-final` suffix. This applies to ALL newly created messages, regardless of whether existing messages in the file have this suffix. Format: `{message-key}.ai-non-final`. Example: `applinks.administration.list.applinks-table.system-label.ai-non-final`. This suffix indicates the message is AI-generated and may need review before finalization.', 'Replace hardcoded strings with either formatMessage(messageKey) or <FormattedMessage id="..." defaultMessage="..." description="..." /> based on existing pattern', '**CRITICAL: Write comprehensive descriptions** - Descriptions are instructions for translators. Include: (1) Where text is shown and the UI element (e.g., "on a button", "as an error message", "as a title", "for a link", "as a drop-down item"), (2) What it does, triggers, or prompts, (3) If there is a placeholder, explain how it will be substituted and with what, (4) If there is an ICU MessageFormat statement (not a placeholder!), provide instruction on the resolved ICU message, not on the ICU structure unless there are more than 2 plural statements, (5) Explain the purpose of the sentence in defaultMessage, (6) Propose an alternative text in Plain English only if the text contains an idiom. Descriptions must be 40+ chars and unique from defaultMessage.', 'Remove eslint-disable for no-literal-string-in-jsx ONLY after converting', '**VERIFICATION**: To verify all hardcoded strings are fixed, search for `@atlassian/i18n/no-literal-string-in-jsx` in the file. Do NOT run eslint - just search for the eslint-disable comments. If no matches are found, all hardcoded strings have been converted.'],
   patterns: [{
     title: 'Button Text and Action Labels',
     description: 'Converting hardcoded button text with variables',
     before: `<Button style={styles} onClick={onClearVersion}>
   Exit {description.join(' ')}
 </Button>`,
-    after: `import { useIntl, defineMessage } from '@atlassian/jira-intl';
+    after: `import { useIntl, defineMessage } from '@jira/platform__react-intl';
 
 const exitButton = defineMessage({
   id: 'rovo-ai-search.exit-button.ai-non-final',
@@ -52,7 +52,7 @@ export function MyComponent() {
     </Badge>
   )}
 </Box>`,
-    after: `import { useIntl, defineMessage } from '@atlassian/jira-intl';
+    after: `import { useIntl, defineMessage } from '@jira/platform__react-intl';
 
 const statusLabel = defineMessage({
   id: 'filter.status-label.ai-non-final',
@@ -83,7 +83,7 @@ export function MyComponent() {
     title: 'Dynamic Text Content',
     description: 'Converting conditional hardcoded strings',
     before: `<Text>{state.hasMore ? 'Show more' : 'Show less'}</Text>`,
-    after: `import { useIntl, defineMessage } from '@atlassian/jira-intl';
+    after: `import { useIntl, defineMessage } from '@jira/platform__react-intl';
 
 const showMore = defineMessage({
   id: 'work-item.comments.show-more.ai-non-final',
@@ -113,7 +113,7 @@ export function MyComponent() {
     title: 'ICU Format for Numeric Values',
     description: 'Converting numeric placeholders to ICU plural format',
     before: `const moreMessage = \`+ \${count} more\`;`,
-    after: `import { useIntl, defineMessage } from '@atlassian/jira-intl';
+    after: `import { useIntl, defineMessage } from '@jira/platform__react-intl';
 
 const moreProjectsMessage = defineMessage({
   id: 'app.more-projects.ai-non-final',
@@ -231,6 +231,6 @@ export function MyComponent() {
     explanation: "Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}. In this example, label and placeholder props use formatMessage(), while button text and content use FormattedMessage."
   }],
   bestPractices: ['Use descriptive names (userNameLabel not label) and placeholders (userName not value)', 'Use ICU plural format for numeric values: {count, plural, one {...} other {...}}', 'When using formatMessage pattern: Place message constants at top of file. When using FormattedMessage pattern: Define messages inline in JSX.', "Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}.", 'Convert arrow functions to body form if needed for hooks'],
-  commonPitfalls: ["**CRITICAL**: Converting strings that don't have eslint-disable comments - only convert strings with @atlassian/i18n/no-literal-string-in-jsx eslint-disable comments. Field labels and other strings without these comments should remain as-is.", '**CRITICAL**: Converting/removing eslint-disable for strings matching ignore patterns - technical/non-user-facing strings should remain hardcoded', '**CRITICAL**: Forgetting to remove eslint-disable comments after conversion - once a string is converted to use formatMessage/FormattedMessage, the eslint-disable comment must be removed', 'Using wrong import path - "jira" path needs @atlassian/jira-intl (with eslint-disable), others use react-intl', 'Adding eslint-disable for defineMessage in non-Jira files or forgetting it in Jira files', 'Missing useIntl hook when using formatMessage pattern, generic placeholder names, descriptions < 40 chars, or descriptions that do not follow the translator guidelines (missing UI element location, missing action explanation, etc.)', "Using placeholder names that don't match variable names - placeholder names in defaultMessage must exactly match the keys in the values object or formatMessage parameters", 'Modifying pre-existing messages or working outside specified path scope'],
+  commonPitfalls: ["**CRITICAL**: Converting strings that don't have eslint-disable comments - only convert strings with @atlassian/i18n/no-literal-string-in-jsx eslint-disable comments. Field labels and other strings without these comments should remain as-is.", '**CRITICAL**: Converting/removing eslint-disable for strings matching ignore patterns - technical/non-user-facing strings should remain hardcoded', '**CRITICAL**: Forgetting to remove eslint-disable comments after conversion - once a string is converted to use formatMessage/FormattedMessage, the eslint-disable comment must be removed', 'Using wrong import path - "jira" path needs @jira/platform__react-intl (with eslint-disable), others use react-intl', 'Adding eslint-disable for defineMessage in non-Jira files or forgetting it in Jira files', 'Missing useIntl hook when using formatMessage pattern, generic placeholder names, descriptions < 40 chars, or descriptions that do not follow the translator guidelines (missing UI element location, missing action explanation, etc.)', "Using placeholder names that don't match variable names - placeholder names in defaultMessage must exactly match the keys in the values object or formatMessage parameters", 'Modifying pre-existing messages or working outside specified path scope'],
   additionalResources: ['ESLint rule @atlassian/i18n/no-literal-string-in-jsx defines ignore patterns for technical strings (URLs, product names, symbols, etc.)']
 };

package/dist/es2019/tools/i18n-conversion/list-i18n-conversion-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { i18nConversionInputSchema } from './i18n-conversion-input-schema';
 export const listI18nConversionTool = {
   name: 'ads_i18n_conversion_guide',
-  description: `Returns a **bundled** step-by-step guide for replacing hardcoded UI strings with \`formatMessage\` (and related patterns) using @atlassian/jira-intl or react-intl: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.
+  description: `Returns a **bundled** step-by-step guide for replacing hardcoded UI strings with \`formatMessage\` (and related patterns) using @jira/platform__react-intl or react-intl: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.
 
 When working with i18n or hardcoded UI strings, use this tool alongside the Context Engine MCP tool \`get_i18n_docs\` for Atlassian-wide Traduki / i18n standards (message definition, extraction, pluralisation, formatting, workflow); this tool supplies the concrete hardcoded-string → \`formatMessage\` playbook bundled in ADS MCP.