Skip to content

Commit 51ba959

Browse files
bigprofbigprof
committed
Add internationalization page to help
1 parent 408ab14 commit 51ba959

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

‎pages/application-features/i18n-internationalization.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Internationalization (i18n) and localizing your AppGini app
3+
linkTitle: Internationalization (i18n)
4+
slug: help/application-features/i18n-internationalization
5+
description: Learn how to localize your AppGini app to any language you want, including translating the app interface, table and field names, and more.
6+
keywords: internationalization, i18n, localization, language, translate, translation, localizing, localisation, appgini, app, application, table, field, name, title, interface, detail view, home page, group, title, application title, child table, tab, column, programmatically, access, localized, strings
7+
---
8+
9+
AppGini applications are internationalization-ready, meaning you can easily localize your app to any language you want.
10+
This is done by creating a translating the generated `language.php` file, which contains all the strings used in your app interface.
11+
AppGini provides a built-in translation tool to help you with this task.
12+
13+
In this page, we'll discuss how to localize your AppGini app to a new language. We'll also discuss how
14+
to localize able and field names, which are not included in the `language.php` file.
15+
16+
## Localizing your app interface (`language.php`)
17+
18+
### Downloading a pre-translated language file
19+
20+
AppGini users have contributed translations to many languages.
21+
These are available for download from the [language files page](https://bigprof.com/appgini/download-language-files).
22+
check that page to see if a translation for your desired language is already available. If it is, you can download it
23+
into your application's main directory, replacing the existing `language.php` file.
24+
25+
As we introduce new features and strings in AppGini, the language file might become incomplete,
26+
so you might need to update it from time to time.
27+
28+
In case you need to translate your app to a language that is not available in the language files page,
29+
or if you need to update an existing translation, you can use the built-in translation tool in AppGini.
30+
31+
### Using the built-in translation tool
32+
33+
Starting with AppGini 22.11, we've added a built-in translation tool to help you translate your app to any language you want.
34+
To use this tool, follow these steps:
35+
36+
1. Sign in to your application as admin.
37+
2. Click the 'Admin area' link at the top of the page.
38+
3. Open the 'Utilities' menu and click 'Translation tool'.
39+
40+
Here is a video showing how to use the translation tool:
41+
42+
<video style="width: 100%; height: auto;" controls>
43+
<source src="https://cdn.bigprof.com/screencasts/appgini-22.11-translation-tool.mp4" type="video/mp4">
44+
Your browser does not support the video tag.
45+
</video>
46+
47+
In the above video, we're translating the words 'Admin area' into the Arabic words 'منطقة الإدارة'.
48+
49+
### Language fallback
50+
51+
If a string is not found in the `language.php` file, AppGini will fall back to the English string,
52+
which is included in the generated `defaultLang.php` file.
53+
54+
## Right to left (RTL) languages
55+
56+
AppGini supports right-to-left (RTL) languages, such as Arabic and Hebrew.
57+
To enable RTL support in your app, open your application's project file in AppGini,
58+
click the 'Application theme' icon in the toolbar, and check the 'RTL' checkbox.
59+
60+
![Enable RTL support in your app](https://cdn.bigprof.com/images/enable-rtl-layout.png "Enable RTL support in your app")
61+
62+
## Localizing table and field names
63+
64+
The `language.php` file contains strings used in the app interface, such as buttons, labels, and messages.
65+
However, it does not contain table and field names. To localize these, you can open the AXP project file in AppGini,
66+
click on the table or field you want to localize, and enter the localized name in the 'Caption' box.
67+
68+
![Localizing table and field names](https://cdn.bigprof.com/images/localize-table-field-names.png "Localizing table and field names")
69+
70+
## Localizing the detail view (record editing form) title
71+
72+
By default, the title of the detail view (record editing form) is 'Detail view'. You can localize this title
73+
by opening the AXP project file in AppGini, clicking the table you want to localize, and entering the localized
74+
title in the 'Detail view title' box. See the screenshot below:
75+
76+
![How to change the detail view title](https://cdn.bigprof.com/images/detail-view-title.png "How to change the detail view title")
77+
78+
And here is the detail view of the orders table with the localized German title 'Bestellungsdetails':
79+
80+
![Detail view with localized title](https://cdn.bigprof.com/images/detail-view-localized-title.png "Detail view with localized title")
81+
82+
## Localizing the home page table group titles
83+
84+
AppGini allows you to group similar tables under a common title in the home page.
85+
This makes it easier for users to navigate your app. You can use localized titles for these groups.
86+
To set the table group title:
87+
88+
1. Open the AXP project file in AppGini.
89+
2. Click the table you want to localize.
90+
3. Click the button titled 'Table group' to open the 'Table groups' dialog.
91+
4. Click the table group you want to localize.
92+
5. Press **`F2`** or the 'Rename' button to rename the group.
93+
94+
![Localizing table group titles](https://cdn.bigprof.com/images/localize-table-group-titles.png "Localizing table group titles")
95+
96+
Here is the home page of the app with the table group title localized to Greek:
97+
98+
![Home page with localized table group title](https://cdn.bigprof.com/images/home-page-localized-table-group-title.png "Home page with localized table group title")
99+
100+
> **Note**: After renaming the table group to some non-Latin characters, you might see question marks or other unexpected characters in the group title
101+
> in AppGini. This is a known issue in AppGini and does not affect the actual display of the group title in the app.
102+
103+
## Localizing the application title
104+
105+
The application title is displayed in the browser's title bar and in the top-left corner of the app.
106+
You can set it to a localized title by opening the AXP project file in AppGini, clicking the topmost node
107+
in the project browser tree at the left, then pressing **`F2`** to rename the application. Underscores in the application name
108+
will be replaced with spaces in the displayed title.
109+
110+
Non-Latin characters in the application title would cause an error message and won't be accepted by AppGini.
111+
As a workaround, you can set the application title to a Latin name, then, after generating the app, you can
112+
edit the generated `hooks/header-extras.php` or `hooks/footer-extras.php` and add the following code:
113+
114+
```html
115+
<script>
116+
const appTitle = 'Διαχειριστής Συντήρησης Ενοικιαζόμενης Περιουσίας';
117+
document.querySelector('a.navbar-brand').innerHTML = `<i class="glyphicon glyphicon-home"></i> ${appTitle}`;
118+
document.title = appTitle;
119+
</script>
120+
```
121+
122+
Replace the Greek text in the `appTitle` variable with your localized application title. Here is the result of the above code:
123+
124+
![Home page with localized table group title](https://cdn.bigprof.com/images/home-page-localized-table-group-title.png "Home page with localized table group title")
125+
126+
## Localizing the titles of child tables
127+
128+
When you have a parent table with child tables, for example, a parent table `shippers` with a child table `orders`,
129+
you can configure the `shippers` table to display the child orders as a tab in the detail view as shown below:
130+
131+
![Child table as a tab in the detail view](https://cdn.bigprof.com/images/child-table-as-tab.png "Child table as a tab in the detail view")
132+
133+
You can also display the count of child orders as a column in the parent shippers table as shown below:
134+
135+
![Child table count as a column in the parent table](https://cdn.bigprof.com/images/child-table-count-as-column.png "Child table count as a column in the parent table")
136+
137+
For both of the above screenshots, the title of the child orders table is set as 'Orders via shipper'. We can localize this title
138+
by opening the AXP project file in AppGini, clicking the parent table (in this case, `shippers`), then clicking the **Parent/children settings**
139+
button to open the **Parent/children settings** dialog.
140+
141+
![Opening the parent/children settings dialog](https://cdn.bigprof.com/images/parent-children-settings.png "Opening the parent/children settings dialog")
142+
143+
Click the desired child table from the grid at the left if not already selected, then enter the localized title in the **Tab/Column title** box.
144+
145+
> **Note**: If the title contains non-Latin characters, you might see question marks or other unexpected characters in the title in the grid.
146+
> This is a known issue in AppGini and does not affect the actual display of the title in the app.
147+
148+
## Programmatically accessing localized strings
149+
150+
You can access localized strings in your hooks using the PHP variable `$Translation`. This is an associative array
151+
where the keys are English strings/short codes and the values are the localized strings. This variable is defined
152+
in `language.php` and can be made available inside any PHP hook function by including the following line at the top of the function:
153+
154+
```php
155+
global $Translation;
156+
```
157+
158+
You can then access any localized string by its English string/short code as follows:
159+
160+
```php
161+
echo $Translation['last modified']; // --> 'zuletzt geändert' in German
162+
```
163+
164+
You can also access localized strings using the `AppGini.Translate._map` JavaScript object. For example:
165+
166+
```javascript
167+
console.log(AppGini.Translate._map['last modified']); // --> 'zuletzt geändert' in German
168+
```
169+
170+

0 commit comments

Comments
 (0)