Skip to content

Localization Process

Jump to bottom
lmarceau edited this page Nov 15, 2023 · 45 revisions

Overview

For documentation on how to add strings in the repo, please look into this wiki page.

The following document gives a step by step guide for the string localization process, meaning the import and the export of strings and their translations in our project.

Github action import process

The string import refers to the import of strings from the l10n repository to the Firefox for iOS repository. The string export refers to the reverse action, which is to export strings from the Firefox for iOS repository to the l10n repository. Both of those actions are handled by Github actions. The import action lives in Firefox for iOS, while the export action lives in the l10n repository. The Firefox for iOS team is responsible for reviewing the import PRs opened towards main and releases, and ensuring the strings added in the repo are following the l10n rules. See documentation on how to add strings for this.

Import

String import from the firefoxios-l10n repository happens once a week and points to the main branch. The Github action opens a PR, which then needs to be reviewed and merged by the developer team. Importing strings can also be done by pointing to a certain branch. For example, on hard freeze a string import can be triggered by running the Create a PR with changes after importing strings workflow, and writing down the targeted version of the branch as shown in following picture:

Screen Shot 2022-09-12 at 1 36 19 PM

Export

String export happens by adding new strings into the Firefox for iOS strings file. Any developer adding new strings to the project should be familiar with the principles described in l10n documentation.

See documentation on how to add strings for the detailed steps.

Manual String import process

⚠️ Shouldn't be done anymore, use Github actions instead to import and export. This documentation is here for now in case it would be needed to debug the string import/export process. ⚠️

Requirements for manual string import

This following repos are the required to run the localization process.

A note on this process. If you run sh ./bootstrap.sh --importLocales this will bootstrap the main Firefox-iOS repo and also download the localization tools and l10n repo in the firefox-ios folder and you don't have to do it manually.

You can also do this manually, of course. Either way, note the location of the l10n repo as you will need it later.

Manual Setup

Now that you have everything you need, here are the steps you need to take for localization.

  • When you begin the process always pull the latest firefoxios-l10n master branch. This ensures that you have the latest strings from translators before you do an export and prevents discrepancies when we're exporting.
  • Open the LocalizationTools project. If you have an error, you might need to adjust the swift-tools-version, located in Package.swift. Either upgrade or downgrade it depending on your swift-tools-version. As of Sep 2021, 5.4 will work fine.
  • Now, click Edit scheme and select the Run scheme.
  • Add arguments to the scheme to configure what you're doing
   --project-path "project-path" Sets the project path to firefox-ios. This should point to wherever your Client.xcodeproj is, and specify the project file in the path as well. You should write the full path to the Client.xcodeproj, which can be found using pwd command in a terminal.
   --l10n-project-path "l10n-project-path" Sets the path to the firefoxios-l10n repo. You should write the full path to the firefoxios-l10n repo, which can be found using pwd command in a terminal.
   --export/import Depending on whether you want to run an export/import task
   --version show the version
   --help show help information

Manual Imports

⚠️ Shouldn't be done anymore, use Github actions instead to import. This documentation is here for now in case it would be needed to debug the string import/export process. ⚠️ Note: Even if your goal is to export, you still need to import first. This ensures that string translation fixes for existing strings are present during the export.

After setting the arguments above, let it run with the --import argument. Importing will take a while. Be aware that you'll see lots of errors & warnings in the console. You can ignore these - it won't affect your import process.

After the process is complete, you'll see a list of files modified in your firefox-ios repo. If your goal was to import newly available/translated strings, you can commit the necessary files and create a PR on firefox-ios. Import runs, but there are no changes on the firefox-ios repo

One reason this may be happening is because of how Xcode is named on your system. If you have multiple versions of Xcode, you may have named them Xcode 13.0, Xcode 12.4 etc. In the logs, look for:

Command line invocation: /Applications/Xcode 13.0.app/Contents/Developer/usr/bin/xcodebuild -importLocalizations -project ...

The Xcode part of the command line invocation, in this example, should be /Applications/Xcode\ 13.0.app/... but it seems that it doesn't get called correctly. You must rename your Xcode, in this situation, to not have a space - Xcode13.0 in this example. This should fix the problem and allow you to import successfully. Manual Exports

⚠️ Shouldn't be done anymore, use Github actions instead to export. This documentation is here for now in case it would be needed to debug the string import/export process. ⚠️ Note: Imports need to happen before you do an export! Follow the process above and come back here after.

  • Be sure that new string comments are understandable to localizers. Make sure comments are descriptive and don't rely on knowing the context of the new string.
  • Here, we'll switch to the --export argument
    • Importing will result in changes in firefox-ios. Exporting will result in changes in firefoxios-l10n.
  • Each locale modification will need a separate commit. You can use this bash script (for now)

#! /usr/bin/env bash

l10n_file="firefox-ios.xliff" locale_list=$(find . -mindepth 1 -maxdepth 1 -type d ( ! -iname ".*" ) | sed 's|^./||g' | sort) for locale in ${locale_list}; do git add ${locale}/${l10n_file} git commit -m "${locale}: Update ${l10n_file}" done

  • Push your branch to your fork
  • Make a PR to firefoxios-l10n repo master
  • Once the PR has been approved, merge
  • Once we are notified that the strings have been translated, we'll have to do another import on a branch off of main in the firefox-ios repo
  • Make a PR and double check that everything shows up correctly

You have now achieved expert level status on String Localization. Rejoice. Celebrate! Do a victory dance!!!

Clone this wiki locally