[action_basics] add localization content IJSDK-886

update README for action_basics

basics/action_system.md

@@ -162,6 +162,36 @@ A different context, such as searching for the action using **Help \| Find Actio
 A second `override-text` element uses `place` and `use-text-of-place` attributes to declare the same version of the text used in the Main Menu is also used in the Editor Popup Menu.
 Additional `override-text` elements could be used to specify additional places where the Main Menu text should be used. 
 
+An example of using `<override-text>` is demonstrated in the [Creating Actions](/tutorials/action_system/working_with_custom_actions.md#using-override-text-for-an-action) tutorial.
+
+#### Localizing Actions and Groups
+Action and group localization use resource bundles containing property files, each file consisting of `key=value` pairs.
+The [`action_basics`](https://github.com/JetBrains/intellij-sdk-code-samples/tree/master/action_basics) plugin demonstrates using a resource bundle to localize the group and action entries added to the Editor Popup Menu.
+
+When localizing actions and groups, the `text=""` and `description=""` attributes are not declared in `plugin.xml`. 
+Instead, those attribute values vary depending on the locale and get declared in a resource bundle.
+
+The name and location of the resource bundle must be declared in the `plugin.xml` file.
+In the case of `action_basics`, only a default localization resource bundle is provided: 
+
+```xml
+  <resource-bundle>messages.BasicActionsBundle</resource-bundle>
+```
+
+For Actions, the `key` in property files incorporates the action `id` in this specific structure:
+* `action.<action-id>.text=Translated Action Text`  
+* `action.<action-id>.description=Translated Action Description` 
+
+If `<override-text>` is used for an action `id`, the `key` includes the `<place>` attribute:
+* `action.<action-id>.<place>.text=Place-dependent Translated Action Text` 
+* `action.<action-id>.<place>.description=Place-dependent Translated Action Description` 
+
+For Groups, the `key` in the property files incorporates the group `id` in this specific structure:
+* `group.<group-id>.text=Translated Group Text` 
+* `group.<group-id>.description=Translated Group Description` 
+
+See [Extending DefaultActionGroup](/tutorials/action_system/grouping_action.md#extending-defaultactiongroup) for a tutorial of localizing Actions and Groups.
+ 
 #### Action Declaration Reference
 The places where actions can appear are defined by constants in [`ActionPlaces`](upsource:///platform/platform-api/src/com/intellij/openapi/actionSystem/ActionPlaces.java). 
 Group IDs for the IntelliJ Platform are defined in [`PlatformActions.xml`](upsource:///platform/platform-resources/src/idea/PlatformActions.xml). 
@@ -247,6 +277,12 @@ This, and additional information can also be found by using the [Code Completion
            a <mouse-shortcut> element. See <keyboard-shortcut> for documentation.  -->
     <mouse-shortcut keymap="$default" keystroke="control button3 doubleClick"/>
   </action>
+  <!--  This action declares neither a text nor description attribute. If it has 
+        a resource bundle declared the text and descriptions will be retrieved
+        based on the action-id incorporated in the key for a translated string -->
+  <action id="sdk.action.PopupDialogAction" class="sdk.action.PopupDialogAction"
+        icon="SdkIcons.Sdk_default_icon">
+  </action> 
   <!-- The <group> element defines an action group. <action>, <group> and 
        <separator> elements defined within it are automatically included in the group.
        The mandatory "id" attribute specifies a unique identifier for the action.

code_samples/action_basics/README.md

@@ -1,16 +1,19 @@
-# Action Sample Project [![JetBrains IntelliJ Platform SDK Docs](https://jb.gg/badges/docs.svg)][docs]
+# Action Basics Sample Project [![JetBrains IntelliJ Platform SDK Docs](https://jb.gg/badges/docs.svg)][docs]
 *Reference: [Action System in IntelliJ SDK Docs][docs:actions]*
 
 ## Quickstart
 
-Action Sample Project demonstrates registering actions process in various configurations.
-Each action is an extension of the [`AnAction`][sdk:AnAction] abstract class and brings the possibility of extending IDE with an event performed with the user interaction - i.e., clicking the button, using the keyboard or mouse shortcuts.
-
-Plugin registers the [`PopupDialogAction`][file:PopupDialogAction] action, which provides a popup dialog as a feedback, in three different ways:
+The Action Basics Sample Project demonstrates the process of registering actions in various configurations.
+Each action is an extension of the [`AnAction`][sdk:AnAction] abstract class and brings the possibility of extending the IDE with an event performed with the user interaction - i.e., clicking the button, using the keyboard or mouse shortcuts.
 
+This Plugin registers the [`PopupDialogAction`][file:PopupDialogAction] action, which provides a popup dialog as a feedback, in three different ways:
 - by assigning the keyboard (<kbd>Ctrl/Cmd</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd>, <kbd>C</kbd>) and mouse shortcuts (<kbd>Ctrl/Cmd</kbd> + <kbd>Mouse Button 3</kbd> + <kbd>Double Click</kbd>),
-- by adding action item to the `ToolsMenu` group, available in Tools menu,
-- by adding action item to the `EditorPopupMenu` group, available in Editor's context menu.
+- by adding an action to the `ToolsMenu` directly, and as part of new groups added to the Tools menu,
+- by adding an action to a new group in the `EditorPopupMenu`, which is the Editor's context menu.
+
+Additional features of the plugin:
+- [Using the `<override-text>`][docs:action-override] element in an `<action>` element is demonstrated in the `plugin.xml` declaration to add the `PopupDialogAction` action directly to the `ToolsMenu`.
+- [Localization of action and group][docs:action-locale] `text` and `description` attributes using a `<resource-bundle>` is demonstrated in the declaration to add a new group to the `EditorPopupMenu`. 
 
 ### Actions
 
@@ -27,6 +30,8 @@ Plugin registers the [`PopupDialogAction`][file:PopupDialogAction] action, which
 
 [docs]: https://www.jetbrains.org/intellij/sdk/docs
 [docs:actions]: https://www.jetbrains.org/intellij/sdk/docs/basics/action_system.html
+[docs:action-override]: https://www.jetbrains.org/intellij/sdk/docs/basics/action_system.html#setting-the-override-text-element-for-an-action
+[docs:action-locale]: https://www.jetbrains.org/intellij/sdk/docs/basics/action_system.html#localizing-actions-and-groups
 
 [file:PopupDialogAction]: ./src/main/java/org/intellij/sdk/action/PopupDialogAction.java
 [file:CustomDefaultActionGroup]: ./src/main/java/org/intellij/sdk/action/CustomDefaultActionGroup.java

code_samples/action_basics/src/main/java/org/intellij/sdk/action/CustomDefaultActionGroup.java

@@ -26,7 +26,7 @@ public class CustomDefaultActionGroup extends DefaultActionGroup {
     // Enable/disable depending on whether user is editing
     Editor editor = event.getData(CommonDataKeys.EDITOR);
     event.getPresentation().setEnabled(editor != null);
-    // Take this opportunity to set an icon for the menu entry.
+    // Take this opportunity to set an icon for the group.
     event.getPresentation().setIcon(SdkIcons.Sdk_default_icon);
   }
 

code_samples/action_basics/src/main/resources/META-INF/plugin.xml

@@ -30,46 +30,61 @@
   <!-- Text to display as company information on Preferences/Settings | Plugin page -->
   <vendor url="https://plugins.jetbrains.com">IntelliJ Platform SDK</vendor>
 
+  <!-- Declare the default resource location for localizing menu strings -->
+  <resource-bundle>messages.BasicActionsBundle</resource-bundle>
+
   <actions>
     <!--
       See https://www.jetbrains.org/intellij/sdk/docs/basics/action_system.html#registering-actions-in-pluginxml
       for information about the elements and attributes used for actions and groups.
-      The <action> element adds a static menu item in first position of the Tools menu that shows PopupDialogAction.
+
+      This <action> element adds a static menu item in first position of the Tools menu that shows PopupDialogAction.
+      Note this element has no text or description attributes because translations for them are given
+      by action-id in the resource-bundle.
+      An <override-text> element is also used for demonstration purposes to show alternate text and description strings
+      for this action's entries in the MainMenu. (Which includes the ToolsMenu. Try commenting out the override-text
+      element and see how the menu text changes.) The alternate text and description attributes do not
+      appear here because they are defined by action-id in the resource-bundle.
     -->
     <action id="org.intellij.sdk.action.PopupDialogAction" class="org.intellij.sdk.action.PopupDialogAction"
             text="Action Basics Plugin: Pop Dialog Action" description="SDK action example"
             icon="SdkIcons.Sdk_default_icon">
+      <add-to-group group-id="ToolsMenu" anchor="first"/>
       <override-text place="MainMenu" text="Pop Dialog Action"/>
       <keyboard-shortcut first-keystroke="control alt A" second-keystroke="C" keymap="$default"/>
       <mouse-shortcut keystroke="control button3 doubleClick" keymap="$default"/>
-      <add-to-group group-id="ToolsMenu" anchor="first"/>
     </action>
     <!--
       All of the following menu groups add the action PopupDialogAction to menus in different ways.
       Note that even though these groups reuse the same action class, in each use the action ids are unique.
+
       GroupedActions demonstrates declaring an action group using the default ActionGroup implementation provided by the
       IntelliJ Platform framework. (Note the lack of a group "class" attribute.) GroupedActions gets inserted after
       PopupDialogAction in the Tools menu. Because the group's implementation is default, it cannot impose
       enable/disable conditions. Instead it must rely on the conditions imposed by the parent menu where it is inserted.
       It declares one action in the group.
     -->
-    <group id="org.intellij.sdk.action.GroupedActions" text="Static Grouped Actions" popup="true"
-           icon="SdkIcons.Sdk_default_icon">
+    <group id="org.intellij.sdk.action.GroupedActions"
+           text="Static Grouped Actions" description="SDK statically grouped action example"
+           popup="true" icon="SdkIcons.Sdk_default_icon">
       <add-to-group group-id="ToolsMenu" anchor="after" relative-to-action="org.intellij.sdk.action.PopupDialogAction"/>
-      <action class="org.intellij.sdk.action.PopupDialogAction" id="org.intellij.sdk.action.GroupPopDialogAction"
-              text="A Group Action" description="SDK static grouped action example" icon="SdkIcons.Sdk_default_icon">
+      <action id="org.intellij.sdk.action.GroupPopDialogAction" class="org.intellij.sdk.action.PopupDialogAction"
+              text="A Group Action" description="SDK static grouped action example"
+              icon="SdkIcons.Sdk_default_icon">
       </action>
     </group>
     <!--
       CustomDefaultActionGroup demonstrates declaring an action group based on a ActionGroup class supplied by this
       plugin. This group is to be inserted atop the Editor Popup Menu. It declares one action in the group.
+      The group and action implementations are internationalized, so their declarations do not use the text or
+      description attributes. Instead, the information is defined in the BasicActionsBundle.
     -->
     <group id="org.intellij.sdk.action.CustomDefaultActionGroup"
-           class="org.intellij.sdk.action.CustomDefaultActionGroup" popup="true"
-           text="Popup Grouped Actions" description="Custom defaultActionGroup demo" icon="SdkIcons.Sdk_default_icon">
+           class="org.intellij.sdk.action.CustomDefaultActionGroup"
+           popup="true">
       <add-to-group group-id="EditorPopupMenu" anchor="first"/>
-      <action class="org.intellij.sdk.action.PopupDialogAction" id="org.intellij.sdk.action.CustomGroupedAction"
-              text="A Popup Action" description="SDK popup grouped action example" icon="SdkIcons.Sdk_default_icon"/>
+      <action id="org.intellij.sdk.action.CustomGroupedAction" class="org.intellij.sdk.action.PopupDialogAction"
+              icon="SdkIcons.Sdk_default_icon"/>
     </group>
     <!--
       DynamicActionGroup demonstrates declaring an action group without a static action declaration.

code_samples/action_basics/src/main/resources/messages/BasicActionsBundle.properties

@@ -0,0 +1,8 @@
+# Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+# Default plugin action and group texts and descriptions go here.
+# All of these example "translated" strings have suffix "[en]" to symbolize they are translated.
+# The suffix is meaningless to the localization process.
+action.org.intellij.sdk.action.CustomGroupedAction.text=A Popup Action[en]
+action.org.intellij.sdk.action.CustomGroupedAction.description=SDK popup grouped action example[en]
+group.org.intellij.sdk.action.CustomDefaultActionGroup.text=Popup Grouped Actions[en]
+group.org.intellij.sdk.action.CustomDefaultActionGroup.description=Custom defaultActionGroup demo[en]

tutorials/action_system/grouping_action.md

@@ -95,37 +95,60 @@ to create the `CustomDefaultActionGroup` class in the `action_basics` code sampl
 
 ### Registering the Custom Action Group
 As in the case with the static action group, the action `<group>` should be declared in the `<actions>` section of the `plugin.xml` file, for example, the [action_basics](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/action_basics/src/main/resources/META-INF/plugin.xml) plugin. 
-The declaration below shows:
-* The presence of the `class` attribute in the `<group>` element, which tells the IntelliJ Platform framework to use `CustomDefaultActionGroup` rather than the default implementation.
-* Setting the group's `popup` attribute to allow submenus. 
+For demonstration purposes, this implementation will use localization.
+
+The `<group>` element declaration below shows:
+* An optional resource bundle declaration outside of the `<actions>` section for localizing actions.
+* The presence of the `class` attribute in the `<group>` element tells the IntelliJ Platform framework to use `CustomDefaultActionGroup` rather than the default implementation.
+* Setting the group's `popup` attribute to allow submenus.
+* The `text` and `description` attributes are omitted in the `<group>` declaration in favor of using the localization resource bundle to define them.
+* There is no `icon` attribute for the group; the `CustomDefaultActionGroup` implementation will [add an icon for the group](#providing-specific-behavior-for-the-custom-group).
 * The `<add-to-group>` element specifies adding the group in the first position of the existing `EditorPopupMenu`.
 
 ```xml
-   <group id="org.jetbrains.tutorials.actions.ExampleCustomDefaultActionGroup" 
-        class="org.jetbrains.tutorials.actions.CustomDefaultActionGroup" popup="true"
-        text="Example Custom DefaultActionGroup" description="Custom DefaultActionGroup Demo">
+  <resource-bundle>messages.BasicActionsBundle</resource-bundle>
+
+  <actions>
+    <group id="org.intellij.sdk.action.CustomDefaultActionGroup"
+           class="org.intellij.sdk.action.CustomDefaultActionGroup"
+           popup="true">
       <add-to-group group-id="EditorPopupMenu" anchor="first"/>
     </group>
+  </actions>
 ```
 
 ### Adding Actions to the Custom Group
 As in [Static Grouped Actions](#adding-a-new-action-to-the-static-grouped-actions), the `PopupDialogAction` action is added as an `<action>` element in the `<group>` element. 
-In the declaration below, note:
-  * The `class` attribute in the `<action>` element has the same FQN to reuse this action implementation.
-  * The `id` attribute is unique to distinguish it from other uses of the implementation in the Action System.
+In the `<action>` element declaration below:
+* The `class` attribute in the `<action>` element has the same FQN to reuse this action implementation.
+* The `id` attribute is unique to distinguish it from other uses of the implementation in the Action System.
+* The `text` and `description` attributes are omitted in the `<action>` declaration; they are instead defined using the localization resource bundle.
+* The SDK icon is declared for use with this action.
    
 ```xml
-    <group id="org.intellij.sdk.action.CustomDefaultActionGroup" class="org.intellij.sdk.action.CustomDefaultActionGroup" popup="true"
-            text="Popup Grouped Actions" description="Custom defaultActionGroup demo" icon="SdkIcons.Sdk_default_icon">
+    <group id="org.intellij.sdk.action.CustomDefaultActionGroup"
+           class="org.intellij.sdk.action.CustomDefaultActionGroup"
+           popup="true" icon="SdkIcons.Sdk_default_icon">
       <add-to-group group-id="EditorPopupMenu" anchor="first"/>
-      <action class="org.intellij.sdk.action.PopupDialogAction" id="org.intellij.sdk.action.CustomGroupedAction"
-              text="A Popup Action" description="SDK popup grouped action example" icon="SdkIcons.Sdk_default_icon"/>
+      <action id="org.intellij.sdk.action.CustomGroupedAction" class="org.intellij.sdk.action.PopupDialogAction"
+              icon="SdkIcons.Sdk_default_icon"/>
     </group>
 ```
 
+Now the translations for the `text` and `description` attributes must be provided in the resource bundle [`BasicActionsBundle.properties`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/master/action_basics/src/main/resources/messages/BasicActionsBundle.properties) file according to [Localizing Actions and Groups](/basics/action_system.md#localizing-actions-and-groups).
+Note there are two sets of `text` and `description` translations, one for the action and one for the group.
+Conceivably, there could be another set of translations for the action if it used the `<override-text>` attribute.
+
+```properties
+action.org.intellij.sdk.action.CustomGroupedAction.text=A Popup Action[en]
+action.org.intellij.sdk.action.CustomGroupedAction.description=SDK popup grouped action example[en]
+group.org.intellij.sdk.action.CustomDefaultActionGroup.text=Popup Grouped Actions[en]
+group.org.intellij.sdk.action.CustomDefaultActionGroup.description=Custom defaultActionGroup demo[en]
+```
+
 ### Providing Specific Behavior for the Custom Group
 Override the `CustomDefaultActionGroup.update()` method to make the group visible only if there's an instance of the editor available. 
-Also, a custom icon is added to demonstrate that icons can be changed depending on the action context:
+Also, a custom icon is added to demonstrate that group icons can be changed depending on the action context:
 
 ```java
 public class CustomDefaultActionGroup extends DefaultActionGroup {
@@ -134,16 +157,17 @@ public class CustomDefaultActionGroup extends DefaultActionGroup {
     // Enable/disable depending on whether user is editing
     Editor editor = event.getData(CommonDataKeys.EDITOR);
     event.getPresentation().setEnabled(editor != null);
-    // Take this opportunity to set an icon for the menu entry.
+    // Take this opportunity to set an icon for the group.
     event.getPresentation().setIcon(SdkIcons.Sdk_default_icon);
   }
 }
 ```
 
-After compiling and running the code sample above and opening a file in the editor and right-clicking, the **Editing** menu will pop up containing a new group of actions in the first position. 
+After compiling and running the code sample above and opening a file in the editor and right-clicking, the **Editing** menu will pop up containing a new group of actions in the first position.
+Note the group and actions come from the resource file as all contain the suffix "[en]". 
 The new group will also have an icon:
 
-![Custom Action Group](img/editor_popup_menu.png){:width="600px"}
+![Custom Action Group](img/editor_popup_menu.png)
   
 
 ## Action Groups with Variable Actions Sets