@atlaskit/ads-mcp 0.13.4 → 0.13.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @atlaskit/ads-mcp
|
|
2
2
|
|
|
3
|
+
## 0.13.5
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`6da0cd3dc1b0f`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/6da0cd3dc1b0f) -
|
|
8
|
+
Improve i18n mcp for better detection on existing patterns and save tokens
|
|
9
|
+
|
|
3
10
|
## 0.13.4
|
|
4
11
|
|
|
5
12
|
### Patch Changes
|
|
@@ -11,42 +11,48 @@ exports.i18nConversionGuide = void 0;
|
|
|
11
11
|
var i18nConversionGuide = exports.i18nConversionGuide = {
|
|
12
12
|
id: 'hardcoded-string-to-formatmessage',
|
|
13
13
|
title: 'Hardcoded String to formatMessage Conversion Guide',
|
|
14
|
-
description: 'Comprehensive guide for converting hardcoded strings to use formatMessage from @atlassian/jira-intl or react-intl-next',
|
|
15
|
-
purpose: 'This guide instructs LLM agents to convert hardcoded strings to use formatMessage. The import source depends on the file path: use @atlassian/jira-intl for Jira files (path contains "jira"), and react-intl-next for any non-Jira files. The goal is to find all hardcoded strings in JSX and convert them to internationalized messages.',
|
|
16
|
-
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.\n\n**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.\n\n**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 and convert them all. The line numbers are just a reference point - the goal is to fix all i18n violations in the provided file.\n\n**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.",
|
|
17
|
-
implementationChecklist: ['
|
|
14
|
+
description: 'Comprehensive guide for converting hardcoded strings to use formatMessage or FormattedMessage from @atlassian/jira-intl or react-intl-next',
|
|
15
|
+
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-next for any non-Jira files. **CRITICAL: Check for existing imports** - If the file already imports from react-intl-next 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.',
|
|
16
|
+
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.\n\n**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.\n\n**CRITICAL: ONLY CONVERT STRINGS WITH ESLINT-DISABLE**: You MUST **ONLY** convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT proactively convert strings that don't have these comments. For example, field labels like `label=\"Space Name\"` that don't have eslint-disable comments should be LEFT AS-IS - they may be acceptable as-is or intentionally not internationalized. Only convert strings that explicitly have the eslint-disable comment indicating they need to be fixed.\n\n**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.\n\n**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.",
|
|
17
|
+
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-next 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-next" for non-Jira files. Note: "react-intl" and "react-intl-next" are treated the same way - both use the same API. When adding to existing imports, maintain alphabetical order: import { defineMessage, FormattedMessage } from "react-intl-next";', '**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.'],
|
|
18
18
|
patterns: [{
|
|
19
19
|
title: 'Button Text and Action Labels',
|
|
20
20
|
description: 'Converting hardcoded button text with variables',
|
|
21
21
|
before: "<Button style={styles} onClick={onClearVersion}>\n Exit {description.join(' ')}\n</Button>",
|
|
22
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst exitButton = defineMessage({\n id: 'rovo-ai-search.exit-button.ai-non-final',\n defaultMessage: 'Exit {version}',\n
|
|
22
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst exitButton = defineMessage({\n id: 'rovo-ai-search.exit-button.ai-non-final',\n defaultMessage: 'Exit {version}',\n\tdescription: 'This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., \"Exit v2.0\"). After a user clicks on the button, it will exit the version view and return to the main view. Appears in the version header.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Button style={styles} onClick={onClearVersion}>\n {formatMessage(exitButton, { version: description.join(' ') })}\n </Button>\n );\n}",
|
|
23
23
|
explanation: 'Convert button text with variables to use placeholders in the message. Use descriptive placeholder names that match the variable context.'
|
|
24
|
-
}, {
|
|
25
|
-
title: 'Loading States and Status Messages',
|
|
26
|
-
description: 'Converting hardcoded loading and status messages',
|
|
27
|
-
before: "return <Box>Loading...</Box>;",
|
|
28
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst loading = defineMessage({\n id: 'rovo-ai-search.loading.ai-non-final',\n defaultMessage: 'Loading...',\n description: 'The text is shown as a loading indicator when work item data is being fetched from the server. Appears in the work item tab to inform users that content is loading.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Box>\n {formatMessage(loading)}\n </Box>\n );\n}",
|
|
29
|
-
explanation: 'Convert simple hardcoded status messages to use defineMessage (singular). Use defineMessage for each individual message, NOT defineMessages. Ensure descriptions explain when and where the message appears.'
|
|
30
24
|
}, {
|
|
31
25
|
title: 'Partial String Translation (Prefixes and Labels)',
|
|
32
26
|
description: 'Translating only part of a string while preserving UI structure',
|
|
33
27
|
before: "<Box xcss={styles}>\n <span>Status: {selectedOptions[0]?.label}</span>\n {selectedOptions.length > 1 && (\n <Badge appearance=\"primary\" max={99}>\n +{selectedOptions.length - 1}\n </Badge>\n )}\n</Box>",
|
|
34
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst statusLabel = defineMessage({\n id: 'filter.status-label.ai-non-final',\n defaultMessage: 'Status: {status}',\n
|
|
28
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst statusLabel = defineMessage({\n id: 'filter.status-label.ai-non-final',\n defaultMessage: 'Status: {status}',\n\tdescription: 'This is the text shown as a button label prefix for the status filter. The placeholder {status} will be substituted with the selected status label (e.g., \"Status: In Progress\"). Appears in the filter button to show the current filter state.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Box xcss={styles}>\n <span>\n {formatMessage(statusLabel, {\n status: selectedOptions[0]?.label,\n })}\n </span>\n {selectedOptions.length > 1 && (\n <Badge appearance=\"primary\" max={99}>\n +{selectedOptions.length - 1}\n </Badge>\n )}\n </Box>\n );\n}",
|
|
35
29
|
explanation: 'When only part of a string needs translation (like a prefix "Status: " or label), create a message with a placeholder for the dynamic part. Preserve the existing UI structure (components, conditional rendering, etc.) and only translate the literal string portion.'
|
|
36
30
|
}, {
|
|
37
31
|
title: 'Dynamic Text Content',
|
|
38
32
|
description: 'Converting conditional hardcoded strings',
|
|
39
33
|
before: "<Text>{state.hasMore ? 'Show more' : 'Show less'}</Text>",
|
|
40
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst showMore = defineMessage({\n id: 'work-item.comments.show-more.ai-non-final',\n defaultMessage: 'Show more',\n
|
|
34
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst showMore = defineMessage({\n id: 'work-item.comments.show-more.ai-non-final',\n defaultMessage: 'Show more',\n\tdescription: 'This is the text on a button. It appears when there are more items available to display. After a user clicks on the button, it will expand the view to show additional content. Used in the comments section footer.',\n});\n\nconst showLess = defineMessage({\n id: 'work-item.comments.show-less.ai-non-final',\n defaultMessage: 'Show less',\n\tdescription: 'This is the text on a button. It appears when the user wants to collapse the expanded view. After a user clicks on the button, it will hide the additional content that was previously expanded. Used in the comments section footer.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Text>\n {state.hasMore\n ? formatMessage(showMore)\n : formatMessage(showLess)}\n </Text>\n );\n}",
|
|
41
35
|
explanation: 'Create separate message constants for each conditional string. Use descriptive names that reflect the context.'
|
|
42
36
|
}, {
|
|
43
37
|
title: 'ICU Format for Numeric Values',
|
|
44
38
|
description: 'Converting numeric placeholders to ICU plural format',
|
|
45
39
|
before: "const moreMessage = `+ ${count} more`;",
|
|
46
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst moreProjectsMessage = defineMessage({\n id: 'app.more-projects.ai-non-final',\n defaultMessage: '{count, plural, one {+ # more} other {+ # more}}',\n
|
|
40
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst moreProjectsMessage = defineMessage({\n id: 'app.more-projects.ai-non-final',\n defaultMessage: '{count, plural, one {+ # more} other {+ # more}}',\n\tdescription: 'This is the text shown when there are additional projects available. The variable {count} will be substituted with the number of remaining projects, and the message will display accordingly (e.g., \"+ 5 more\" or \"+ 1 more\"). Appears to indicate how many more items can be viewed.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n const count = 5;\n\n return (\n <Text>\n {formatMessage(moreProjectsMessage, { count })}\n </Text>\n );\n}",
|
|
47
41
|
explanation: 'Use ICU plural format for numeric values that may need pluralization. The # symbol represents the numeric value in ICU format.'
|
|
42
|
+
}, {
|
|
43
|
+
title: 'Using FormattedMessage',
|
|
44
|
+
description: 'Reusing existing FormattedMessage pattern and using with placeholders',
|
|
45
|
+
before: "import { FormattedMessage } from 'react-intl-next';\n\nexport function MyComponent() {\n const version = 'v2.0';\n return (\n <Box>\n <FormattedMessage {...existingMessage} />\n <Button>Save changes</Button>\n <Button>\n Exit {version}\n </Button>\n </Box>\n );\n}",
|
|
46
|
+
after: "import { FormattedMessage } from 'react-intl-next';\n\nexport function MyComponent() {\n const version = 'v2.0';\n return (\n <Box>\n <FormattedMessage {...existingMessage} />\n <Button>\n <FormattedMessage\n id=\"my-component.save-button.ai-non-final\"\n defaultMessage=\"Save changes\"\n description=\"This is the text on a button. After a user clicks on the button, it will initiate the form being submitted. Appears in the form footer to save changes.\"\n />\n </Button>\n <Button>\n <FormattedMessage\n id=\"my-component.exit-button.ai-non-final\"\n defaultMessage=\"Exit {version}\"\n description=\"This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., \"Exit v2.0\"). After a user clicks on the button, it will exit the version view and return to the main view.\"\n values={{ version }}\n />\n </Button>\n </Box>\n );\n}",
|
|
47
|
+
explanation: 'When FormattedMessage is already used in the file, reuse the existing import. Define message details directly inline in FormattedMessage component props (id, defaultMessage, description). No need to use defineMessage - FormattedMessage accepts these props directly. For dynamic values, use the values prop - the placeholder names in defaultMessage must match the keys in the values object.'
|
|
48
|
+
}, {
|
|
49
|
+
title: 'formatMessage() vs <FormattedMessage> - When to Use Each',
|
|
50
|
+
description: 'Choosing between formatMessage() and FormattedMessage based on context',
|
|
51
|
+
before: "<Field name=\"spaceName\" label=\"Space Name\" placeholder=\"Enter space name\" />\n<Button aria-label=\"Create space\">Create space</Button>\n<Box>Welcome message</Box>",
|
|
52
|
+
after: "import { defineMessage, FormattedMessage, useIntl } from 'react-intl-next';\n\nconst spaceNameLabel = defineMessage({\n id: 'my-component.space-name-label.ai-non-final',\n defaultMessage: 'Space Name',\n description: 'This is the text shown as a label for the space name input field. Appears above the input field to identify what information should be entered.',\n});\n\nconst spaceNamePlaceholder = defineMessage({\n id: 'my-component.space-name-placeholder.ai-non-final',\n defaultMessage: 'Enter space name',\n description: 'This is the placeholder text shown inside the space name input field when it is empty. Provides guidance to users on what to enter in the field.',\n});\n\nconst createSpaceAriaLabel = defineMessage({\n id: 'my-component.create-space-aria-label.ai-non-final',\n defaultMessage: 'Create space',\n description: 'This is the accessible label for the create space button. Used by screen readers to announce the button purpose. The button will create a new space when clicked.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <>\n <Field\n name=\"spaceName\"\n label={formatMessage(spaceNameLabel)}\n placeholder={formatMessage(spaceNamePlaceholder)}\n />\n <Button aria-label={formatMessage(createSpaceAriaLabel)}>\n <FormattedMessage\n id=\"my-component.create-space-button.ai-non-final\"\n defaultMessage=\"Create space\"\n description=\"This is the text on a button. After a user clicks on the button, it will create a new space. Appears as the primary action button in the form.\"\n />\n </Button>\n <Box>\n <FormattedMessage\n id=\"my-component.welcome-message.ai-non-final\"\n defaultMessage=\"Welcome message\"\n description=\"This is the text shown as a welcome message. Appears in the main content area to greet users when they first visit the page.\"\n />\n </Box>\n </>\n );\n}",
|
|
53
|
+
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."
|
|
48
54
|
}],
|
|
49
|
-
bestPractices: ['
|
|
50
|
-
commonPitfalls: [
|
|
55
|
+
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'],
|
|
56
|
+
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-next', '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'],
|
|
51
57
|
additionalResources: ['ESLint rule @atlassian/i18n/no-literal-string-in-jsx defines ignore patterns for technical strings (URLs, product names, symbols, etc.)']
|
|
52
58
|
};
|
|
@@ -5,16 +5,18 @@
|
|
|
5
5
|
export const i18nConversionGuide = {
|
|
6
6
|
id: 'hardcoded-string-to-formatmessage',
|
|
7
7
|
title: 'Hardcoded String to formatMessage Conversion Guide',
|
|
8
|
-
description: 'Comprehensive guide for converting hardcoded strings to use formatMessage from @atlassian/jira-intl or react-intl-next',
|
|
9
|
-
purpose: 'This guide instructs LLM agents to convert hardcoded strings to use formatMessage. The import source depends on the file path: use @atlassian/jira-intl for Jira files (path contains "jira"), and react-intl-next for any non-Jira files. The goal is to find all hardcoded strings in JSX and convert them to internationalized messages.',
|
|
8
|
+
description: 'Comprehensive guide for converting hardcoded strings to use formatMessage or FormattedMessage from @atlassian/jira-intl or react-intl-next',
|
|
9
|
+
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-next for any non-Jira files. **CRITICAL: Check for existing imports** - If the file already imports from react-intl-next 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.',
|
|
10
10
|
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.
|
|
11
11
|
|
|
12
12
|
**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.
|
|
13
13
|
|
|
14
|
-
**CRITICAL:
|
|
14
|
+
**CRITICAL: ONLY CONVERT STRINGS WITH ESLINT-DISABLE**: You MUST **ONLY** convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT proactively convert strings that don't have these comments. For example, field labels like \`label="Space Name"\` that don't have eslint-disable comments should be LEFT AS-IS - they may be acceptable as-is or intentionally not internationalized. Only convert strings that explicitly have the eslint-disable comment indicating they need to be fixed.
|
|
15
|
+
|
|
16
|
+
**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.
|
|
15
17
|
|
|
16
18
|
**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.`,
|
|
17
|
-
implementationChecklist: ['
|
|
19
|
+
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-next 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-next" for non-Jira files. Note: "react-intl" and "react-intl-next" are treated the same way - both use the same API. When adding to existing imports, maintain alphabetical order: import { defineMessage, FormattedMessage } from "react-intl-next";', '**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.'],
|
|
18
20
|
patterns: [{
|
|
19
21
|
title: 'Button Text and Action Labels',
|
|
20
22
|
description: 'Converting hardcoded button text with variables',
|
|
@@ -26,7 +28,7 @@ export const i18nConversionGuide = {
|
|
|
26
28
|
const exitButton = defineMessage({
|
|
27
29
|
id: 'rovo-ai-search.exit-button.ai-non-final',
|
|
28
30
|
defaultMessage: 'Exit {version}',
|
|
29
|
-
|
|
31
|
+
description: 'This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., "Exit v2.0"). After a user clicks on the button, it will exit the version view and return to the main view. Appears in the version header.',
|
|
30
32
|
});
|
|
31
33
|
|
|
32
34
|
export function MyComponent() {
|
|
@@ -39,28 +41,6 @@ export function MyComponent() {
|
|
|
39
41
|
);
|
|
40
42
|
}`,
|
|
41
43
|
explanation: 'Convert button text with variables to use placeholders in the message. Use descriptive placeholder names that match the variable context.'
|
|
42
|
-
}, {
|
|
43
|
-
title: 'Loading States and Status Messages',
|
|
44
|
-
description: 'Converting hardcoded loading and status messages',
|
|
45
|
-
before: `return <Box>Loading...</Box>;`,
|
|
46
|
-
after: `import { useIntl, defineMessage } from '@atlassian/jira-intl';
|
|
47
|
-
|
|
48
|
-
const loading = defineMessage({
|
|
49
|
-
id: 'rovo-ai-search.loading.ai-non-final',
|
|
50
|
-
defaultMessage: 'Loading...',
|
|
51
|
-
description: 'The text is shown as a loading indicator when work item data is being fetched from the server. Appears in the work item tab to inform users that content is loading.',
|
|
52
|
-
});
|
|
53
|
-
|
|
54
|
-
export function MyComponent() {
|
|
55
|
-
const { formatMessage } = useIntl();
|
|
56
|
-
|
|
57
|
-
return (
|
|
58
|
-
<Box>
|
|
59
|
-
{formatMessage(loading)}
|
|
60
|
-
</Box>
|
|
61
|
-
);
|
|
62
|
-
}`,
|
|
63
|
-
explanation: 'Convert simple hardcoded status messages to use defineMessage (singular). Use defineMessage for each individual message, NOT defineMessages. Ensure descriptions explain when and where the message appears.'
|
|
64
44
|
}, {
|
|
65
45
|
title: 'Partial String Translation (Prefixes and Labels)',
|
|
66
46
|
description: 'Translating only part of a string while preserving UI structure',
|
|
@@ -77,7 +57,7 @@ export function MyComponent() {
|
|
|
77
57
|
const statusLabel = defineMessage({
|
|
78
58
|
id: 'filter.status-label.ai-non-final',
|
|
79
59
|
defaultMessage: 'Status: {status}',
|
|
80
|
-
|
|
60
|
+
description: 'This is the text shown as a button label prefix for the status filter. The placeholder {status} will be substituted with the selected status label (e.g., "Status: In Progress"). Appears in the filter button to show the current filter state.',
|
|
81
61
|
});
|
|
82
62
|
|
|
83
63
|
export function MyComponent() {
|
|
@@ -108,13 +88,13 @@ export function MyComponent() {
|
|
|
108
88
|
const showMore = defineMessage({
|
|
109
89
|
id: 'work-item.comments.show-more.ai-non-final',
|
|
110
90
|
defaultMessage: 'Show more',
|
|
111
|
-
|
|
91
|
+
description: 'This is the text on a button. It appears when there are more items available to display. After a user clicks on the button, it will expand the view to show additional content. Used in the comments section footer.',
|
|
112
92
|
});
|
|
113
93
|
|
|
114
94
|
const showLess = defineMessage({
|
|
115
95
|
id: 'work-item.comments.show-less.ai-non-final',
|
|
116
96
|
defaultMessage: 'Show less',
|
|
117
|
-
|
|
97
|
+
description: 'This is the text on a button. It appears when the user wants to collapse the expanded view. After a user clicks on the button, it will hide the additional content that was previously expanded. Used in the comments section footer.',
|
|
118
98
|
});
|
|
119
99
|
|
|
120
100
|
export function MyComponent() {
|
|
@@ -138,7 +118,7 @@ export function MyComponent() {
|
|
|
138
118
|
const moreProjectsMessage = defineMessage({
|
|
139
119
|
id: 'app.more-projects.ai-non-final',
|
|
140
120
|
defaultMessage: '{count, plural, one {+ # more} other {+ # more}}',
|
|
141
|
-
|
|
121
|
+
description: 'This is the text shown when there are additional projects available. The variable {count} will be substituted with the number of remaining projects, and the message will display accordingly (e.g., "+ 5 more" or "+ 1 more"). Appears to indicate how many more items can be viewed.',
|
|
142
122
|
});
|
|
143
123
|
|
|
144
124
|
export function MyComponent() {
|
|
@@ -152,8 +132,105 @@ export function MyComponent() {
|
|
|
152
132
|
);
|
|
153
133
|
}`,
|
|
154
134
|
explanation: 'Use ICU plural format for numeric values that may need pluralization. The # symbol represents the numeric value in ICU format.'
|
|
135
|
+
}, {
|
|
136
|
+
title: 'Using FormattedMessage',
|
|
137
|
+
description: 'Reusing existing FormattedMessage pattern and using with placeholders',
|
|
138
|
+
before: `import { FormattedMessage } from 'react-intl-next';
|
|
139
|
+
|
|
140
|
+
export function MyComponent() {
|
|
141
|
+
const version = 'v2.0';
|
|
142
|
+
return (
|
|
143
|
+
<Box>
|
|
144
|
+
<FormattedMessage {...existingMessage} />
|
|
145
|
+
<Button>Save changes</Button>
|
|
146
|
+
<Button>
|
|
147
|
+
Exit {version}
|
|
148
|
+
</Button>
|
|
149
|
+
</Box>
|
|
150
|
+
);
|
|
151
|
+
}`,
|
|
152
|
+
after: `import { FormattedMessage } from 'react-intl-next';
|
|
153
|
+
|
|
154
|
+
export function MyComponent() {
|
|
155
|
+
const version = 'v2.0';
|
|
156
|
+
return (
|
|
157
|
+
<Box>
|
|
158
|
+
<FormattedMessage {...existingMessage} />
|
|
159
|
+
<Button>
|
|
160
|
+
<FormattedMessage
|
|
161
|
+
id="my-component.save-button.ai-non-final"
|
|
162
|
+
defaultMessage="Save changes"
|
|
163
|
+
description="This is the text on a button. After a user clicks on the button, it will initiate the form being submitted. Appears in the form footer to save changes."
|
|
164
|
+
/>
|
|
165
|
+
</Button>
|
|
166
|
+
<Button>
|
|
167
|
+
<FormattedMessage
|
|
168
|
+
id="my-component.exit-button.ai-non-final"
|
|
169
|
+
defaultMessage="Exit {version}"
|
|
170
|
+
description="This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., "Exit v2.0"). After a user clicks on the button, it will exit the version view and return to the main view."
|
|
171
|
+
values={{ version }}
|
|
172
|
+
/>
|
|
173
|
+
</Button>
|
|
174
|
+
</Box>
|
|
175
|
+
);
|
|
176
|
+
}`,
|
|
177
|
+
explanation: 'When FormattedMessage is already used in the file, reuse the existing import. Define message details directly inline in FormattedMessage component props (id, defaultMessage, description). No need to use defineMessage - FormattedMessage accepts these props directly. For dynamic values, use the values prop - the placeholder names in defaultMessage must match the keys in the values object.'
|
|
178
|
+
}, {
|
|
179
|
+
title: 'formatMessage() vs <FormattedMessage> - When to Use Each',
|
|
180
|
+
description: 'Choosing between formatMessage() and FormattedMessage based on context',
|
|
181
|
+
before: `<Field name="spaceName" label="Space Name" placeholder="Enter space name" />
|
|
182
|
+
<Button aria-label="Create space">Create space</Button>
|
|
183
|
+
<Box>Welcome message</Box>`,
|
|
184
|
+
after: `import { defineMessage, FormattedMessage, useIntl } from 'react-intl-next';
|
|
185
|
+
|
|
186
|
+
const spaceNameLabel = defineMessage({
|
|
187
|
+
id: 'my-component.space-name-label.ai-non-final',
|
|
188
|
+
defaultMessage: 'Space Name',
|
|
189
|
+
description: 'This is the text shown as a label for the space name input field. Appears above the input field to identify what information should be entered.',
|
|
190
|
+
});
|
|
191
|
+
|
|
192
|
+
const spaceNamePlaceholder = defineMessage({
|
|
193
|
+
id: 'my-component.space-name-placeholder.ai-non-final',
|
|
194
|
+
defaultMessage: 'Enter space name',
|
|
195
|
+
description: 'This is the placeholder text shown inside the space name input field when it is empty. Provides guidance to users on what to enter in the field.',
|
|
196
|
+
});
|
|
197
|
+
|
|
198
|
+
const createSpaceAriaLabel = defineMessage({
|
|
199
|
+
id: 'my-component.create-space-aria-label.ai-non-final',
|
|
200
|
+
defaultMessage: 'Create space',
|
|
201
|
+
description: 'This is the accessible label for the create space button. Used by screen readers to announce the button purpose. The button will create a new space when clicked.',
|
|
202
|
+
});
|
|
203
|
+
|
|
204
|
+
export function MyComponent() {
|
|
205
|
+
const { formatMessage } = useIntl();
|
|
206
|
+
|
|
207
|
+
return (
|
|
208
|
+
<>
|
|
209
|
+
<Field
|
|
210
|
+
name="spaceName"
|
|
211
|
+
label={formatMessage(spaceNameLabel)}
|
|
212
|
+
placeholder={formatMessage(spaceNamePlaceholder)}
|
|
213
|
+
/>
|
|
214
|
+
<Button aria-label={formatMessage(createSpaceAriaLabel)}>
|
|
215
|
+
<FormattedMessage
|
|
216
|
+
id="my-component.create-space-button.ai-non-final"
|
|
217
|
+
defaultMessage="Create space"
|
|
218
|
+
description="This is the text on a button. After a user clicks on the button, it will create a new space. Appears as the primary action button in the form."
|
|
219
|
+
/>
|
|
220
|
+
</Button>
|
|
221
|
+
<Box>
|
|
222
|
+
<FormattedMessage
|
|
223
|
+
id="my-component.welcome-message.ai-non-final"
|
|
224
|
+
defaultMessage="Welcome message"
|
|
225
|
+
description="This is the text shown as a welcome message. Appears in the main content area to greet users when they first visit the page."
|
|
226
|
+
/>
|
|
227
|
+
</Box>
|
|
228
|
+
</>
|
|
229
|
+
);
|
|
230
|
+
}`,
|
|
231
|
+
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."
|
|
155
232
|
}],
|
|
156
|
-
bestPractices: ['
|
|
157
|
-
commonPitfalls: [
|
|
233
|
+
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'],
|
|
234
|
+
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-next', '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'],
|
|
158
235
|
additionalResources: ['ESLint rule @atlassian/i18n/no-literal-string-in-jsx defines ignore patterns for technical strings (URLs, product names, symbols, etc.)']
|
|
159
236
|
};
|
|
@@ -5,42 +5,48 @@
|
|
|
5
5
|
export var i18nConversionGuide = {
|
|
6
6
|
id: 'hardcoded-string-to-formatmessage',
|
|
7
7
|
title: 'Hardcoded String to formatMessage Conversion Guide',
|
|
8
|
-
description: 'Comprehensive guide for converting hardcoded strings to use formatMessage from @atlassian/jira-intl or react-intl-next',
|
|
9
|
-
purpose: 'This guide instructs LLM agents to convert hardcoded strings to use formatMessage. The import source depends on the file path: use @atlassian/jira-intl for Jira files (path contains "jira"), and react-intl-next for any non-Jira files. The goal is to find all hardcoded strings in JSX and convert them to internationalized messages.',
|
|
10
|
-
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.\n\n**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.\n\n**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 and convert them all. The line numbers are just a reference point - the goal is to fix all i18n violations in the provided file.\n\n**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.",
|
|
11
|
-
implementationChecklist: ['
|
|
8
|
+
description: 'Comprehensive guide for converting hardcoded strings to use formatMessage or FormattedMessage from @atlassian/jira-intl or react-intl-next',
|
|
9
|
+
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-next for any non-Jira files. **CRITICAL: Check for existing imports** - If the file already imports from react-intl-next 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.',
|
|
10
|
+
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.\n\n**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.\n\n**CRITICAL: ONLY CONVERT STRINGS WITH ESLINT-DISABLE**: You MUST **ONLY** convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT proactively convert strings that don't have these comments. For example, field labels like `label=\"Space Name\"` that don't have eslint-disable comments should be LEFT AS-IS - they may be acceptable as-is or intentionally not internationalized. Only convert strings that explicitly have the eslint-disable comment indicating they need to be fixed.\n\n**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.\n\n**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.",
|
|
11
|
+
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-next 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-next" for non-Jira files. Note: "react-intl" and "react-intl-next" are treated the same way - both use the same API. When adding to existing imports, maintain alphabetical order: import { defineMessage, FormattedMessage } from "react-intl-next";', '**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.'],
|
|
12
12
|
patterns: [{
|
|
13
13
|
title: 'Button Text and Action Labels',
|
|
14
14
|
description: 'Converting hardcoded button text with variables',
|
|
15
15
|
before: "<Button style={styles} onClick={onClearVersion}>\n Exit {description.join(' ')}\n</Button>",
|
|
16
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst exitButton = defineMessage({\n id: 'rovo-ai-search.exit-button.ai-non-final',\n defaultMessage: 'Exit {version}',\n
|
|
16
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst exitButton = defineMessage({\n id: 'rovo-ai-search.exit-button.ai-non-final',\n defaultMessage: 'Exit {version}',\n\tdescription: 'This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., \"Exit v2.0\"). After a user clicks on the button, it will exit the version view and return to the main view. Appears in the version header.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Button style={styles} onClick={onClearVersion}>\n {formatMessage(exitButton, { version: description.join(' ') })}\n </Button>\n );\n}",
|
|
17
17
|
explanation: 'Convert button text with variables to use placeholders in the message. Use descriptive placeholder names that match the variable context.'
|
|
18
|
-
}, {
|
|
19
|
-
title: 'Loading States and Status Messages',
|
|
20
|
-
description: 'Converting hardcoded loading and status messages',
|
|
21
|
-
before: "return <Box>Loading...</Box>;",
|
|
22
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst loading = defineMessage({\n id: 'rovo-ai-search.loading.ai-non-final',\n defaultMessage: 'Loading...',\n description: 'The text is shown as a loading indicator when work item data is being fetched from the server. Appears in the work item tab to inform users that content is loading.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Box>\n {formatMessage(loading)}\n </Box>\n );\n}",
|
|
23
|
-
explanation: 'Convert simple hardcoded status messages to use defineMessage (singular). Use defineMessage for each individual message, NOT defineMessages. Ensure descriptions explain when and where the message appears.'
|
|
24
18
|
}, {
|
|
25
19
|
title: 'Partial String Translation (Prefixes and Labels)',
|
|
26
20
|
description: 'Translating only part of a string while preserving UI structure',
|
|
27
21
|
before: "<Box xcss={styles}>\n <span>Status: {selectedOptions[0]?.label}</span>\n {selectedOptions.length > 1 && (\n <Badge appearance=\"primary\" max={99}>\n +{selectedOptions.length - 1}\n </Badge>\n )}\n</Box>",
|
|
28
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst statusLabel = defineMessage({\n id: 'filter.status-label.ai-non-final',\n defaultMessage: 'Status: {status}',\n
|
|
22
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst statusLabel = defineMessage({\n id: 'filter.status-label.ai-non-final',\n defaultMessage: 'Status: {status}',\n\tdescription: 'This is the text shown as a button label prefix for the status filter. The placeholder {status} will be substituted with the selected status label (e.g., \"Status: In Progress\"). Appears in the filter button to show the current filter state.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Box xcss={styles}>\n <span>\n {formatMessage(statusLabel, {\n status: selectedOptions[0]?.label,\n })}\n </span>\n {selectedOptions.length > 1 && (\n <Badge appearance=\"primary\" max={99}>\n +{selectedOptions.length - 1}\n </Badge>\n )}\n </Box>\n );\n}",
|
|
29
23
|
explanation: 'When only part of a string needs translation (like a prefix "Status: " or label), create a message with a placeholder for the dynamic part. Preserve the existing UI structure (components, conditional rendering, etc.) and only translate the literal string portion.'
|
|
30
24
|
}, {
|
|
31
25
|
title: 'Dynamic Text Content',
|
|
32
26
|
description: 'Converting conditional hardcoded strings',
|
|
33
27
|
before: "<Text>{state.hasMore ? 'Show more' : 'Show less'}</Text>",
|
|
34
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst showMore = defineMessage({\n id: 'work-item.comments.show-more.ai-non-final',\n defaultMessage: 'Show more',\n
|
|
28
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst showMore = defineMessage({\n id: 'work-item.comments.show-more.ai-non-final',\n defaultMessage: 'Show more',\n\tdescription: 'This is the text on a button. It appears when there are more items available to display. After a user clicks on the button, it will expand the view to show additional content. Used in the comments section footer.',\n});\n\nconst showLess = defineMessage({\n id: 'work-item.comments.show-less.ai-non-final',\n defaultMessage: 'Show less',\n\tdescription: 'This is the text on a button. It appears when the user wants to collapse the expanded view. After a user clicks on the button, it will hide the additional content that was previously expanded. Used in the comments section footer.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <Text>\n {state.hasMore\n ? formatMessage(showMore)\n : formatMessage(showLess)}\n </Text>\n );\n}",
|
|
35
29
|
explanation: 'Create separate message constants for each conditional string. Use descriptive names that reflect the context.'
|
|
36
30
|
}, {
|
|
37
31
|
title: 'ICU Format for Numeric Values',
|
|
38
32
|
description: 'Converting numeric placeholders to ICU plural format',
|
|
39
33
|
before: "const moreMessage = `+ ${count} more`;",
|
|
40
|
-
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst moreProjectsMessage = defineMessage({\n id: 'app.more-projects.ai-non-final',\n defaultMessage: '{count, plural, one {+ # more} other {+ # more}}',\n
|
|
34
|
+
after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst moreProjectsMessage = defineMessage({\n id: 'app.more-projects.ai-non-final',\n defaultMessage: '{count, plural, one {+ # more} other {+ # more}}',\n\tdescription: 'This is the text shown when there are additional projects available. The variable {count} will be substituted with the number of remaining projects, and the message will display accordingly (e.g., \"+ 5 more\" or \"+ 1 more\"). Appears to indicate how many more items can be viewed.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n const count = 5;\n\n return (\n <Text>\n {formatMessage(moreProjectsMessage, { count })}\n </Text>\n );\n}",
|
|
41
35
|
explanation: 'Use ICU plural format for numeric values that may need pluralization. The # symbol represents the numeric value in ICU format.'
|
|
36
|
+
}, {
|
|
37
|
+
title: 'Using FormattedMessage',
|
|
38
|
+
description: 'Reusing existing FormattedMessage pattern and using with placeholders',
|
|
39
|
+
before: "import { FormattedMessage } from 'react-intl-next';\n\nexport function MyComponent() {\n const version = 'v2.0';\n return (\n <Box>\n <FormattedMessage {...existingMessage} />\n <Button>Save changes</Button>\n <Button>\n Exit {version}\n </Button>\n </Box>\n );\n}",
|
|
40
|
+
after: "import { FormattedMessage } from 'react-intl-next';\n\nexport function MyComponent() {\n const version = 'v2.0';\n return (\n <Box>\n <FormattedMessage {...existingMessage} />\n <Button>\n <FormattedMessage\n id=\"my-component.save-button.ai-non-final\"\n defaultMessage=\"Save changes\"\n description=\"This is the text on a button. After a user clicks on the button, it will initiate the form being submitted. Appears in the form footer to save changes.\"\n />\n </Button>\n <Button>\n <FormattedMessage\n id=\"my-component.exit-button.ai-non-final\"\n defaultMessage=\"Exit {version}\"\n description=\"This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., \"Exit v2.0\"). After a user clicks on the button, it will exit the version view and return to the main view.\"\n values={{ version }}\n />\n </Button>\n </Box>\n );\n}",
|
|
41
|
+
explanation: 'When FormattedMessage is already used in the file, reuse the existing import. Define message details directly inline in FormattedMessage component props (id, defaultMessage, description). No need to use defineMessage - FormattedMessage accepts these props directly. For dynamic values, use the values prop - the placeholder names in defaultMessage must match the keys in the values object.'
|
|
42
|
+
}, {
|
|
43
|
+
title: 'formatMessage() vs <FormattedMessage> - When to Use Each',
|
|
44
|
+
description: 'Choosing between formatMessage() and FormattedMessage based on context',
|
|
45
|
+
before: "<Field name=\"spaceName\" label=\"Space Name\" placeholder=\"Enter space name\" />\n<Button aria-label=\"Create space\">Create space</Button>\n<Box>Welcome message</Box>",
|
|
46
|
+
after: "import { defineMessage, FormattedMessage, useIntl } from 'react-intl-next';\n\nconst spaceNameLabel = defineMessage({\n id: 'my-component.space-name-label.ai-non-final',\n defaultMessage: 'Space Name',\n description: 'This is the text shown as a label for the space name input field. Appears above the input field to identify what information should be entered.',\n});\n\nconst spaceNamePlaceholder = defineMessage({\n id: 'my-component.space-name-placeholder.ai-non-final',\n defaultMessage: 'Enter space name',\n description: 'This is the placeholder text shown inside the space name input field when it is empty. Provides guidance to users on what to enter in the field.',\n});\n\nconst createSpaceAriaLabel = defineMessage({\n id: 'my-component.create-space-aria-label.ai-non-final',\n defaultMessage: 'Create space',\n description: 'This is the accessible label for the create space button. Used by screen readers to announce the button purpose. The button will create a new space when clicked.',\n});\n\nexport function MyComponent() {\n const { formatMessage } = useIntl();\n\n return (\n <>\n <Field\n name=\"spaceName\"\n label={formatMessage(spaceNameLabel)}\n placeholder={formatMessage(spaceNamePlaceholder)}\n />\n <Button aria-label={formatMessage(createSpaceAriaLabel)}>\n <FormattedMessage\n id=\"my-component.create-space-button.ai-non-final\"\n defaultMessage=\"Create space\"\n description=\"This is the text on a button. After a user clicks on the button, it will create a new space. Appears as the primary action button in the form.\"\n />\n </Button>\n <Box>\n <FormattedMessage\n id=\"my-component.welcome-message.ai-non-final\"\n defaultMessage=\"Welcome message\"\n description=\"This is the text shown as a welcome message. Appears in the main content area to greet users when they first visit the page.\"\n />\n </Box>\n </>\n );\n}",
|
|
47
|
+
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."
|
|
42
48
|
}],
|
|
43
|
-
bestPractices: ['
|
|
44
|
-
commonPitfalls: [
|
|
49
|
+
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'],
|
|
50
|
+
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-next', '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'],
|
|
45
51
|
additionalResources: ['ESLint rule @atlassian/i18n/no-literal-string-in-jsx defines ignore patterns for technical strings (URLs, product names, symbols, etc.)']
|
|
46
52
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/ads-mcp",
|
|
3
|
-
"version": "0.13.
|
|
3
|
+
"version": "0.13.5",
|
|
4
4
|
"description": "The official Atlassian Design System MCP server to develop apps and user interfaces matching the Atlassian style.",
|
|
5
5
|
"author": "Atlassian Pty Ltd",
|
|
6
6
|
"license": "Apache-2.0",
|