opensearch-project · AMoo-Miki · Oct 4, 2023 · Oct 4, 2023
@@ -921,6 +921,30 @@ license.
 
 The following developer guide rules are specific for working with the React framework.
 
+#### Prefer reactDirective over react-component
+
+When using `ngReact` to embed your react components inside Angular HTML, prefer the
+`reactDirective` service over the `react-component` directive.
+You can read more about these two ngReact methods [here](https://github.com/ngReact/ngReact#features).
+
+Using `react-component` means adding a bunch of components into angular, while `reactDirective` keeps them isolated, and is also a more succinct syntax.
+
+**Good:**
+
+```html
+<hello-component
+  fname="person.fname"
+  lname="person.lname"
+  watch-depth="reference"
+></hello-component>
+```
+
+**Bad:**
+
+```html
+<react-component name="HelloComponent" props="person" watch-depth="reference" />
+```
+
 #### Name action functions and prop functions appropriately
 
 Name action functions in the form of a strong verb and passed properties in the form of on<Subject><Change>. E.g:

@@ -163,6 +163,9 @@
     "JSONStream": "1.3.5",
     "abortcontroller-polyfill": "^1.4.0",
     "ajv": "^8.11.0",
+    "angular": "^1.8.2",
+    "angular-elastic": "^2.5.1",
+    "angular-sanitize": "^1.8.0",
     "bluebird": "3.5.5",
     "chalk": "^4.1.0",
     "chokidar": "^3.4.2",
@@ -264,6 +267,8 @@
     "@testing-library/jest-dom": "^5.16.2",
     "@testing-library/react": "^12.1.2",
     "@testing-library/react-hooks": "^7.0.2",
+    "@types/angular": "^1.8.4",
+    "@types/angular-mocks": "^1.7.1",
     "@types/archiver": "^5.3.1",
     "@types/babel__core": "^7.1.17",
     "@types/bluebird": "^3.1.1",
@@ -344,6 +349,10 @@
     "@types/zen-observable": "^0.8.0",
     "@typescript-eslint/eslint-plugin": "^3.10.0",
     "@typescript-eslint/parser": "^3.10.0",
+    "angular-aria": "^1.8.0",
+    "angular-mocks": "^1.8.2",
+    "angular-recursion": "^1.0.5",
+    "angular-route": "^1.8.0",
     "archiver": "^5.3.0",
     "axe-core": "^4.0.2",
     "babel-eslint": "^10.0.3",
@@ -420,6 +429,7 @@
     "ms-chromium-edge-driver": "^0.4.3",
     "murmurhash3js": "3.0.1",
     "mutation-observer": "^1.0.3",
+    "ngreact": "^0.5.1",
     "nock": "12.0.3",
     "node-stream-zip": "^1.15.0",
     "normalize-path": "^3.0.0",
@@ -472,4 +482,4 @@
     "node": ">=14.20.1 <19",
     "yarn": "^1.22.10"
   }
-}
+}
@@ -92,6 +92,17 @@ The long term plan is to rely on using `FormattedMessage` and `i18n.translate()`
 Currently, we support the following ReactJS `i18n` tools, but they will be removed in future releases:
 - Usage of `props.intl.formatmessage()` (where `intl` is  passed to `props` by `injectI18n` HOC).
 
+#### In AngularJS
+
+The long term plan is to rely on using `i18n.translate()` by statically importing `i18n` from the `@osd/i18n` package. **Avoid using the `i18n` filter and the `i18n` service injected in controllers, directives, services.**
+
+- Call JS function `i18n.translate()` from the `@osd/i18n` package.
+- Use `i18nId` directive in template.
+
+Currently, we support the following AngluarJS `i18n` tools, but they will be removed in future releases:
+- Usage of `i18n` service in controllers, directives, services by injecting it.
+- Usage of `i18n` filter in template for attribute translation. Note: Use one-time binding ("{{:: ... }}") in filters wherever it's possible to prevent unnecessary expression re-evaluation.
+
 #### In JavaScript
 
 - Use `i18n.translate()` in NodeJS or any other framework agnostic code, where `i18n` is the I18n engine from `@osd/i18n` package.

@@ -1,13 +1,14 @@
 # I18n
 
-OpenSearch Dashboards relies on UI frameworks (ReactJS) and
+OpenSearch Dashboards relies on several UI frameworks (ReactJS and AngularJS) and
 requires localization in different environments (browser and NodeJS).
 Internationalization engine is framework agnostic and consumable in
-all parts of OpenSearch Dashboards (ReactJS and NodeJS). In order to simplify
+all parts of OpenSearch Dashboards (ReactJS, AngularJS and NodeJS). In order to simplify
 internationalization in UI frameworks, the additional abstractions are
-built around the I18n engine: `react-intl` for React. [React-intl](https://github.com/yahoo/react-intl)
+built around the I18n engine: `react-intl` for React and custom
+components for AngularJS. [React-intl](https://github.com/yahoo/react-intl)
 is built around [intl-messageformat](https://github.com/yahoo/intl-messageformat),
-so the React framework uses the same engine and the same
+so both React and AngularJS frameworks use the same engine and the same
 message syntax.
 
 ## Localization files
@@ -342,6 +343,98 @@ export const MyComponent = injectI18n(
 );
 ```
 
+## AngularJS
+
+The long term plan is to rely on using `i18n.translate()` by statically importing `i18n` from the `@osd/i18n` package. **Avoid using the `i18n` filter and the `i18n` service injected in controllers, directives, services.**
+
+AngularJS wrapper has 4 entities: translation `provider`, `service`, `directive`
+and `filter`. Both the directive and the filter use the translation `service`
+with i18n engine under the hood.
+
+The translation `provider` is used for `service` configuration and
+has the following methods:
+- `addMessages(messages: Map<string, string>, [locale: string])` - provides a way to register
+translations with the library
+- `setLocale(locale: string)` - tells the library which language to use by given
+language key
+- `getLocale()` - returns the current locale
+- `setDefaultLocale(locale: string)` - tells the library which language to fallback
+when missing translations
+- `getDefaultLocale()` - returns the default locale
+- `setFormats(formats: object)` - supplies a set of options to the underlying formatter
+- `getFormats()` - returns current formats
+- `getRegisteredLocales()` - returns array of locales having translations
+- `init(messages: Map<string, string>)` - initializes the engine
+
+The translation `service` provides only one method:
+- `i18n(id: string, { values: object, defaultMessage: string, description: string })` –
+translate message by id
+
+The translation `filter` is used for attributes translation and has
+the following syntax:
+```
+{{ ::'translationId' | i18n: { values: object, defaultMessage: string, description: string } }}
+```
+
+Where:
+- `translationId` - translation id to be translated
+- `values` - values to pass into translation
+- `defaultMessage` - will be used unless translation was successful (the final
+  fallback in english, will be used for generating `en.json`)
+- `description` - optional context comment that will be extracted by i18n tools
+and added as a comment next to translation message at `defaultMessages.json`
+
+The translation `directive` has the following syntax:
+```html
+<ANY
+  i18n-id="{string}"
+  i18n-default-message="{string}"
+  [i18n-values="{object}"]
+  [i18n-description="{string}"]
+></ANY>
+```
+
+Where:
+- `i18n-id` - translation id to be translated
+- `i18n-default-message` - will be used unless translation was successful
+- `i18n-values` - values to pass into translation
+- `i18n-description` - optional context comment that will be extracted by i18n tools
+and added as a comment next to translation message at `defaultMessages.json`
+
+If HTML rendering in `i18n-values` is required then value key in `i18n-values` object
+should have `html_` prefix. Otherwise the value will be inserted to the message without
+HTML rendering.\
+Example:
+```html
+<p
+  i18n-id="namespace.id"
+  i18n-default-message="Text with an emphasized {text}."
+  i18n-values="{
+    html_text: '<em>text</em>',
+  }"
+></p>
+```
+
+Angular `I18n` module is placed into `autoload` module, so it will be
+loaded automatically. After that we can use i18n directive in Angular templates:
+```html
+<span
+  i18n-id="welcome"
+  i18n-default-message="Hello!"
+></span>
+```
+
+In order to translate attributes in AngularJS we should use `i18nFilter`:
+```html
+<input
+  type="text"
+  placeholder="{{ ::'osd.management.objects.searchAriaLabel' | i18n: {
+    defaultMessage: 'Search { title } Object',
+    values: { title }
+  } }}"
+>
+```
+
 ## I18n tools
 
 In order to simplify localization process, some additional tools were implemented:

@@ -0,0 +1,5 @@
+{
+  "browser": "../target/web/angular",
+  "main": "../target/node/angular",
+  "types": "../target/types/angular/index.d.ts"
+}