Skip to content

Commit

Permalink
chore: improve i18n documentation (#9257)
Browse files Browse the repository at this point in the history
  • Loading branch information
splincode authored Sep 30, 2024
1 parent e35d213 commit ca7b1de
Show file tree
Hide file tree
Showing 8 changed files with 185 additions and 70 deletions.
3 changes: 3 additions & 0 deletions projects/cdk/schematics/ng-update/v4/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,18 +41,21 @@ import {
MODULES_TO_REMOVE,
SERVICES_TO_REPLACE,
} from './steps/constants';
import {REPLACE_FUNCTIONS} from './steps/constants/functions';
import {MODULES_TO_REPLACE_WITH_PROVIDERS} from './steps/constants/modules-to-replace';
import {TYPES_TO_RENAME} from './steps/constants/types';
import {dropUniversalMock} from './steps/drop-universal-mock';
import {migrateEditor} from './steps/migrate-editor';
import {migrateImportProvidersFrom} from './steps/migrate-providers-from';
import {migrateRoot} from './steps/migrate-root';
import {replaceFunctions} from './steps/replace-functions';
import {replaceModulesWithProviders} from './steps/utils/replace-modules-with-providers';

function main(options: TuiSchema): Rule {
return (tree: Tree, context: SchematicContext) => {
const fileSystem = getFileSystem(tree);

replaceFunctions(REPLACE_FUNCTIONS);
migrateImportProvidersFrom(options);
migrateEditor(fileSystem, options);
replaceEnums(options, ENUMS_TO_REPLACE);
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import type {ReplacementType} from '../../../interfaces/replacement-type';

export const REPLACE_FUNCTIONS: readonly ReplacementType[] = [
{
from: 'tuiDocLanguageSwitcher',
to: 'tuiLanguageSwitcher',
moduleSpecifier: ['@taiga-ui/i18n'],
},
];
25 changes: 25 additions & 0 deletions projects/cdk/schematics/ng-update/v4/steps/replace-functions.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import {Node} from 'ng-morph';

import {getNamedImportReferences} from '../../../utils/get-named-import-references';
import type {ReplacementType} from '../../interfaces/replacement-type';

export function replaceFunctions(functions: readonly ReplacementType[]): void {
functions.forEach(({from, to, moduleSpecifier}) => {
getNamedImportReferences(from, moduleSpecifier).forEach((ref) => {
if (ref.wasForgotten()) {
return;
}

const parent = ref.getParent();

if (Node.isImportSpecifier(parent) || Node.isCallExpression(parent)) {
parent?.replaceWithText(
parent
?.getText({includeJsDocComments: false})
.trim()
.replace(from, to ?? from),
);
}
});
});
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
import {join} from 'node:path';

import {HostTree} from '@angular-devkit/schematics';
import {SchematicTestRunner, UnitTestTree} from '@angular-devkit/schematics/testing';
import type {TuiSchema} from '@taiga-ui/cdk/schematics/ng-add/schema';
import {
createProject,
createSourceFile,
resetActiveProject,
saveActiveProject,
setActiveProject,
} from 'ng-morph';

import {createAngularJson} from '../../../utils/create-angular-json';

const collectionPath = join(__dirname, '../../../migration.json');

const COMPONENT_BEFORE = `
import {tuiDocLanguageSwitcher} from '@taiga-ui/i18n';
@Component({
standalone: true,
templateUrl: './test.template.html',
providers: [
tuiDocLanguageSwitcher(async (language): Promise<unknown> => {})
]
})
export class Test {
}`;

const COMPONENT_AFTER = `
import {tuiLanguageSwitcher} from '@taiga-ui/i18n';
@Component({
standalone: true,
templateUrl: './test.template.html',
providers: [
tuiLanguageSwitcher(async (language): Promise<unknown> => {})
]
})
export class Test {
}`;

describe('ng-update', () => {
let host: UnitTestTree;
let runner: SchematicTestRunner;

beforeEach(() => {
host = new UnitTestTree(new HostTree());
runner = new SchematicTestRunner('schematics', collectionPath);

setActiveProject(createProject(host));

createMainFiles();

saveActiveProject();
});

it('should migrate i18n references in ts files', async () => {
const tree = await runner.runSchematic(
'updateToV4',
{'skip-logs': process.env['TUI_CI'] === 'true'} as Partial<TuiSchema>,
host,
);

expect(tree.readContent('test/app/test.component.ts')).toEqual(COMPONENT_AFTER);
});

afterEach(() => {
resetActiveProject();
});
});

function createMainFiles(): void {
createSourceFile('test/app/test.component.ts', COMPONENT_BEFORE);

createSourceFile('test/app/test.template.html', '');

createAngularJson();
createSourceFile(
'package.json',
'{"dependencies": {"@angular/core": "~13.0.0", "@taiga-ui/i18n": "~3.42.0"}}',
);
}
5 changes: 2 additions & 3 deletions projects/demo/src/modules/customization/i18n/dynamic.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
```ts
import {TuiLanguageName} from '@taiga-ui/i18n/types';
import {tuiDocLanguageSwitcher} from '@taiga-ui/i18n/switch';
import {tuiLanguageSwitcher, TuiLanguageName} from '@taiga-ui/i18';

bootstrapApplication(App, {
providers: [
// ...
tuiDocLanguageSwitcher(
tuiLanguageSwitcher(
/**
* @note:
* then the i18n language files will be loaded from node_modules
Expand Down
14 changes: 4 additions & 10 deletions projects/demo/src/modules/customization/i18n/esbuild.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,10 @@
```ts
import {TuiLanguageName} from '@taiga-ui/i18n/types';
import {tuiDocLanguageSwitcher} from '@taiga-ui/i18n/utils';
import {tuiLanguageSwitcher, TuiLanguageName} from '@taiga-ui/i18n';

@Component({
standalone: true,
imports: [
// ...
],
bootstrapApplication(App, {
providers: [
// ...
tuiDocLanguageSwitcher(async (language: TuiLanguageName): Promise<unknown> => {
tuiLanguageSwitcher(async (language: TuiLanguageName): Promise<unknown> => {
switch (language) {
case 'belarusian':
return import('@taiga-ui/i18n/languages/belarusian');
Expand Down Expand Up @@ -46,6 +41,5 @@ import {tuiDocLanguageSwitcher} from '@taiga-ui/i18n/utils';
}
}),
],
})
export class Example {}
}).catch((err: unknown) => console.error(err));
```
105 changes: 52 additions & 53 deletions projects/demo/src/modules/customization/i18n/index.html
Original file line number Diff line number Diff line change
@@ -1,59 +1,59 @@
<tui-doc-page header="Internationalization">
<ng-template pageTab="Supported languages">
<p>
You have English by default. If you want to change it, you need to provide
<code>TUI_LANGUAGE</code>
token in your configuration. Full list of supported language
<a
href="https://github.com/taiga-family/taiga-ui/tree/main/projects/i18n/languages"
target="_blank"
tuiLink
>
here
</a>
.
</p>
<tui-doc-page header="Internationalization (i18n)">
<p>
Some components in Taiga UI embedded texts and they use English translate by default. If you want to change it,
you need to provide
<code>TUI_LANGUAGE</code>
token in your configuration. Full list of supported language
<a
href="https://github.com/taiga-family/taiga-ui/tree/main/projects/i18n/languages"
target="_blank"
tuiLink
>
here.
</a>
</p>

<tui-doc-code
filename="main.ts"
class="tui-space_top-5"
[code]="example.base"
/>
</ng-template>
<tui-doc-code
class="tui-space_top-5"
[code]="example.base"
/>

<ng-template pageTab="Dynamic loader">
<tui-doc-code
filename="main.ts"
[code]="example.dynamic"
/>

<tui-doc-example
id="theme-switcher"
[content]="example1"
>
<tui-doc-language-switcher>Language</tui-doc-language-switcher>
</tui-doc-example>
<tui-doc-example
id="theme-switcher"
description="Making custom toggling between different languages"
heading="Language Switcher"
[content]="example1"
[fullsize]="true"
>
<tui-doc-language-switcher />

<h2 class="tui-space_top-10">CLI's esbuild-based build system</h2>
<p>
Dynamic import expressions that do not contain static values will be kept in their original form and not
processed at build time. This is a limitation of the underlying bundler but is
<a
href="https://github.com/evanw/esbuild/pull/2508"
target="_blank"
tuiLink
>
planned
</a>
to be implemented in the future. In many cases, application code can be made to work by changing the import
expressions into static strings with some form of conditional statement such as an if or switch for the
known potential files.
</p>
<tui-table-pagination
class="tui-space_top-5"
[page]="0"
[size]="10"
[total]="237"
/>
</tui-doc-example>

<tui-doc-code [code]="example.esbuild" />
</ng-template>
<tui-accordion class="tui-space_top-5">
<tui-accordion-item>
CLI's webpack-based build system
<ng-template tuiAccordionItemContent>
<tui-doc-code [code]="example.dynamic" />
</ng-template>
</tui-accordion-item>
<tui-accordion-item>
CLI's esbuild-based build system
<ng-template tuiAccordionItemContent>
<tui-doc-code [code]="example.esbuild" />
</ng-template>
</tui-accordion-item>
</tui-accordion>

<ng-template pageTab="How to add a language">
<tui-doc-example
heading="How to add a language"
[fullsize]="true"
>
<p>
1. Go to
<a
Expand All @@ -75,9 +75,8 @@ <h2 class="tui-space_top-10">CLI's esbuild-based build system</h2>
<p>3. Translate entities in files. If you need some clarification, take a look at interfaces of entities</p>

<tui-doc-code
filename="main.ts"
class="tui-space_top-5"
[code]="example.custom"
/>
</ng-template>
</tui-doc-example>
</tui-doc-page>
10 changes: 6 additions & 4 deletions projects/demo/src/modules/customization/i18n/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@ import {Component} from '@angular/core';
import {changeDetection} from '@demo/emulate/change-detection';
import {TuiDemo} from '@demo/utils';
import {TuiDocLanguageSwitcher} from '@taiga-ui/addon-doc';
import {TuiTablePagination} from '@taiga-ui/addon-table';
import {TuiLink} from '@taiga-ui/core';
import {TuiAccordion} from '@taiga-ui/kit';

@Component({
standalone: true,
imports: [TuiDemo, TuiDocLanguageSwitcher, TuiLink],
imports: [TuiAccordion, TuiDemo, TuiDocLanguageSwitcher, TuiLink, TuiTablePagination],
templateUrl: './index.html',
changeDetection,
})
Expand All @@ -19,13 +21,13 @@ export default class Page {
};

protected example1 = {
'language-switcher.component.html': import(
'language-switcher.html': import(
'../../../../../addon-doc/components/language-switcher/index.html?raw'
),
'language-switcher.component.ts': import(
'language-switcher.ts': import(
'../../../../../addon-doc/components/language-switcher/index.ts?raw'
),
'language-switcher.module.less': import(
'language-switcher.less': import(
'../../../../../addon-doc/components/language-switcher/index.less?raw'
),
};
Expand Down

0 comments on commit ca7b1de

Please sign in to comment.