diff --git a/README.md b/README.md index 9d246e9..3010aa8 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ Ilion is (going to be) a localization helper tool for macOS that cuts the length ### About the name -Ilion stands from i(nstant)-localization (l10n), but the name also makes reference to the ancient city of Troy, which the Greeks infiltrated by means of the famous Trojan Horse trick. +Ilion stands for i(nstant)-localization (l10n), but the name also makes reference to the ancient city of Troy, which the Greeks infiltrated by means of the famous Trojan Horse trick. ### What is it good for? -Ilion's purpose is to allow for near-live app localization on macOS. This means that localized strings can be added, removed, or changed run-time, without having to rebuild the project. In some cases, the app should be relaunched in order to see the changes, but sometimes not even that is necessary. Translators who have been suffering from lack of context can now have something real to play with. Checking whether the resizing behavior is properly configured for a text UI element or iterating on a translation until it fits-- all these can now be done with almost instant feedback using Ilion. +Ilion's purpose is to allow for near-live app localization on macOS. This means that localized string overrides can be added, removed, or changed run-time, without having to rebuild the project. In some cases, the app should be relaunched in order to see the changes, but sometimes not even that is necessary. Translators who have been suffering from lack of context can now have something real to play with. Checking whether the resizing behavior is properly configured for a text UI element or iterating on a translation until it fits-- all these can now be done with almost instant feedback using Ilion. -### How does it work +### How does it work? Ilion needs to be built into the target application. When the app is launched, the framework intercepts calls to `NSLocalizedString` and proxies them to a string database built from the `.strings` resources and the previously set overrides. This database can then be accessed and modified via the Ilion UI. @@ -52,11 +52,11 @@ macOS 10.10 - only `.strings`/`.stringsdict` files and UI base localization are supported (that is, one XIB + many strings files) - changes are only preserved on the machine they have been made on -- changes cannot be exported or committed back to the original resources +- changes cannot be committed back into the app bundle ### Planned improvements -- export changes to file +- instant update of changed views - integration with cloud-based translation services ### License diff --git a/doc/GettingStarted.md b/doc/GettingStarted.md index fbec8a5..e73e4db 100644 --- a/doc/GettingStarted.md +++ b/doc/GettingStarted.md @@ -25,6 +25,8 @@ Ilion is not (yet) a replacement for the user interface of cloud-based localizat For Ilion to work, it needs to be explicitly enabled by the developers when the app is built. This usually means that you'll have to ask for a custom build instead of using the publicly released versions. +#### Browsing strings + When you launch the app, you'll notice that in the application menu there is a new menu item named _Launch Ilion_: ![application menu](app_menu.png) @@ -35,16 +37,26 @@ Clicking the menu item brings up the Ilion browser window: This window shows all the modifiable copies in the application for all enabled languages. The rows in bold indicate the copies you have already modified. Use the search field to filter the list. You can also adjust whether you want to see all matching copies, just the ones you have already customized, or the yet untouched ones. +#### Editing strings + Once you find the entry you are looking for, doubleclick on the row (or select it and hit Return) to open the edit panel. ![edit panel](edit_panel_simple.png) -In this panel you can see some metadata about the copy being edited. Here, _Key_ is just an identifier developers use to refer to this string in the code. _Translation_ is the actual text that will be shown to the users, and this is what you can replace by filling out the _Override_ field. When you are done, hit Apply to commit the changes. +In this panel you can see some metadata about the copy being edited. Here, _Key_ is just an identifier developers use to refer to this string in the code. _Comment_ is an optional hint that the developers may have attached to this entry to aid the translation by giving some context. _Translation_ is the actual text that will be shown to the users, and this is what you can replace by filling out the _Override_ field. When you are done, hit Apply to commit the changes. Note: to revert to the original copy, it is not sufficient to clear the text field. Instead, you should go back to the browser window, select the entry from the list, and press Backspace. If you want to start over from scratch, use the _Reset_ button to trash all previous changes. **IMPORTANT:** Changes made to copies are never immediately reflected on the app UI. E.g. if you are customizing texts in a dialog, you'll have to close and reopen the dialog to see the updated texts. Customizing other parts of the application (e.g. the main menu) may even require restarting the app for changes to take effect. This is a known limitation. +### Exporting changes + +Ilion now supports exporting the app's string resources with all the changes that have previously been applied. For this, hit _Export..._ in the bottom right corner of the browser window. + +![export button](export_button.png) + +You are then presented with a file dialog where you can select the directory to save the resources to. When exporting is finished, the exported files will be revealed in the Finder. + ### Advanced topics Ilion currently offers experimental support for plural forms. If a string has been localized with plurals enabled, the edit panel will show a plural rule selector to let you browse through all defined plural rules: diff --git a/doc/browser.png b/doc/browser.png index 27ffd85..44b2a70 100644 Binary files a/doc/browser.png and b/doc/browser.png differ diff --git a/doc/edit_panel_plurals_override.png b/doc/edit_panel_plurals_override.png index e2db022..7501355 100644 Binary files a/doc/edit_panel_plurals_override.png and b/doc/edit_panel_plurals_override.png differ diff --git a/doc/edit_panel_plurals_source.png b/doc/edit_panel_plurals_source.png index 042c109..d074a82 100644 Binary files a/doc/edit_panel_plurals_source.png and b/doc/edit_panel_plurals_source.png differ diff --git a/doc/edit_panel_simple.png b/doc/edit_panel_simple.png index 0bd6a08..4879173 100644 Binary files a/doc/edit_panel_simple.png and b/doc/edit_panel_simple.png differ diff --git a/doc/export_button.png b/doc/export_button.png new file mode 100644 index 0000000..63b7f21 Binary files /dev/null and b/doc/export_button.png differ diff --git a/doc/screenshot.png b/doc/screenshot.png index 38d6540..7be9a03 100644 Binary files a/doc/screenshot.png and b/doc/screenshot.png differ