Over the Air (Strings)

Mit dem SDK überprüft die App regelmäßig auf aktualisierte Übersetzungen und lädt diese im Hintergrund herunter.

Überprüfe regelmäßig die neuesten Releases des Android SDKs, insbesondere im Hinblick auf Upgrades.

Falls Übersetzungen nicht aktualisiert werden:

Wenn die falsche Version einer Übersetzung verwendet wird, stelle sicher, dass ein Release mit den neuesten Übersetzungen und der aktuellen App-Version verfügbar ist und der versionName für die App gesetzt ist und das <major>.<minor>.<point>. Format verwendet wird.

Anforderungen

SDK einbinden

Füge ein neues Repository zur root build.gradle hinzu:

allprojects {
    repositories {
        ...
        maven { url "https://maven.download.phrase.com" }
    }
}

Füge die Bibliothek als Abhängigkeit hinzu:

dependencies {
    implementation "com.phrase.android:ota-sdk:3.5.0"
    ...
}

Jetpack Compose Unterstützung

Um Jetpack Compose Unterstützung für OTA-Übersetzungen zu aktivieren, folge diesen Schritten:

Konfiguration

Initialisiere das SDK in der Anwendungsklasse und füge die Distributions-ID und das Umgebungsgeheimnis hinzu. Klassen, die von Application erben, sollten attachBaseContext überschreiben, um Übersetzungen außerhalb des Aktivitätskontexts zu ermöglichen:

public class MainApplication extends Application {
  @Override
  public void onCreate() {
      super.onCreate();
      Phrase.setup(this, "DISTRIBUTION_ID", "ENVIRONMENT_TOKEN");
      Phrase.updateTranslations();
  }

  @Override
  protected void attachBaseContext(Context newBase) {
    super.attachBaseContext(Phrase.wrapApplicationContext(newBase));
  }  
}

Injiziere das SDK in jede Aktivität, z.B. indem du eine Basisaktivität erstellst, von der alle anderen Aktivitäten erben:

public class BaseActivity extends AppCompatActivity {
  @NonNull
  @Override
  public AppCompatDelegate getDelegate() {
    return Phrase.getDelegate(this, super.getDelegate());
  }
}

Übersetzungen können wie gewohnt in Layouts verwendet werden:

<TextView android:text="@string/translation_key" />

Und im Code:

TextView text = (TextView) findViewById(R.id.text_id);
text.setText(R.string.translation_key);

Einige Bibliotheken unterstützen das automatische Entpacken des Kontexts nicht und erwarten eine spezifische Klasse. In diesem Fall kann das Context-Wrapping in Jetpack Compose-Komponenten deaktiviert werden mit:

Phrase(contextWrapping = false) {
    Text( text = phraseString(R.string.test) )
}

Konfigurationen für Log-Level:

Sprache ändern

Wenn nicht die Systemsprache verwendet wird, kann eine andere Sprache in der Methode setLocaleCode festgelegt werden. Der Sprachcode (locale) muss in einem Release vorhanden sein.

Phrase.setLocaleCode("fr");
Phrase.updateTranslations();

Benutzerdefinierte App-Version

Das SDK verwendet standardmäßig die App-Version, um ein Release zurückzugeben, das den Release-Beschränkungen für die minimale und maximale Version entspricht. Die App-Version muss semantische Versionierung verwenden, sonst wird kein Übersetzungs-Update zurückgegeben. Falls die App keine semantische Versionierung verwendet, ist es möglich, die verwendete App-Version manuell zu überschreiben.

Beispiel:

Phrase.setAppVersion("3.2.4");

Die Version muss festgelegt werden, bevor updateTranslations( ) aufgerufen wird.

Timeout setzen

Das Standard-Timeout für Übersetzungsdownloads ist auf 10s gesetzt.

Das Standard-Timeout kann geändert werden mit:

Phrase.setTimeout(10000); // Timeout in Millisekunden

Update-Callback

Wenn die Bearbeitung erfolgreicher Übersetzungs-Updates erforderlich ist, füge einen Callback-Handler hinzu:

Phrase.updateTranslations(new TranslationsSyncCallback() {
    @Override
    public void onSuccess(boolean translationsChanged) {
    }

    @Override
    public void onFailure() {
    }
});

Übersetzungsupdates können auch manuell ausgelöst werden. Neu abgerufene Übersetzungen werden beim nächsten Start der Anwendung angezeigt.

Um die neuesten Übersetzungen sofort verfügbar zu machen, benutze die Methode Phrase.applyPendingUpdates(). Dies kann mit dem Abbonnieren von Übersetzungsupdates kombiniert werden:

Phrase.updateTranslations(new TranslationsSyncCallback() {
    @Override
    public void onSuccess(boolean translationsChanged) {
      if(translationsChanged) {
         Phrase.applyPendingUpdates()
        // Eigene Logik, um die UI zu aktualisieren
      }
    }

    @Override
    public void onFailure() {
    }
});

Die UI zeigt Übersetzungen nicht automatisch an und muss neu erstellt werden.

Konfiguriere das US-Datencenter

Das Phrase US-Datencenter wird ebenfalls unterstützt. Das US-Datencenter kann durch Aufruf von:

Phrase.setHost("https://ota.us.phrase.com/")

Fallback

Falls es wegen einer fehlenden Netzwerkverbindung des Clients oder einer Dienstunterbrechung nicht möglich ist, Phrase zu erreichen, verwendet das SDK die gebündelten Übersetzungen aus der Ressourcendatei. Das regelmäßige Aktualisieren der gebündelten Übersetzungen in der App wird empfohlen. Das SDK speichert Übersetzungen auch lokal auf dem Gerät. Wenn ein solcher Cache existiert, wird er bis zum nächsten Übersetzungsupdate verwendet.

Das SDK verwendet die aktuellste Veröffentlichung für die Übersetzungen. Falls der versionName für die App festgelegt ist, wird die aktuellste Veröffentlichung verwendet, die die Versionsbeschränkungen erfüllt.

Neue Sprache hinzufügen

Die neue Sprache in Phrase erstellen und eine neue Veröffentlichung erstellen. Das SDK ruft die Sprache ab, wenn dies die Gerätesprache eines Users ist. Regelmäßig eine neue strings.xml für neue Sprachdateien hinzuzufügen, wenn eine neue App-Version veröffentlicht wird, wird empfohlen, sonst sehen die User beim ersten Start der App nur die von Android bestimmten Fallback-Übersetzungen.

Prüfung

Das SDK ist Closed Source und kann nicht eingesehen oder modifiziert werden. Falls es eine Anforderung der Organisation ist, können Prüfungen bereitgestellt werden. Kontaktiere uns für weitere Details, falls erforderlich.

Unterstützung für benutzerdefinierte Ansichten

Benutzerdefinierte Ansichten können mit stilisierten Attributen übersetzt werden. Da TypedArray das Überschreiben der Ressourcen nicht erlaubt, sind leichte Änderungen in der benutzerdefinierten Ansicht erforderlich:

Beispiel-App

https://github.com/phrase/android-sdk-example

Mit dem SDK überprüft die App regelmäßig auf aktualisierte Übersetzungen und lädt diese im Hintergrund herunter.

Anforderungen

Diese Bibliothek hängt von Version 0.18.0 der Flutter intl Bibliothek ab. Folge ihrem Leitfaden, um Unterstützung für Lokalisierungen zur App hinzuzufügen.

Installation

Füge Phrase zur pubspec.yaml hinzu:

dependencies:
  phrase: ^2.5.1 
  ...
  intl: ^0.18.0
  flutter_localizations:
    sdk: flutter
  ...

flutter:
  generate: true
  ...

Wie in der intl-Bibliothek wird Codegenerierung verwendet, um ARB-Dateien zu verarbeiten. Führe diesen Befehl aus, um zu aktualisieren:

flutter pub run phrase

Mit build_runner:

flutter pub run build_runner watch

Verwendung

Initialisiere Phrase in der main.dart-Datei:

import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:flutter_gen/gen_l10n/phrase_localizations.dart';
import 'package:phrase/phrase.dart';

void main() {
  Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]");
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      //..
      localizationsDelegates: PhraseLocalizations.localizationsDelegates,
      supportedLocales: PhraseLocalizations.supportedLocales,
    );
  }
}

Nachrichten abrufen mit:

Text(AppLocalizations.of(context)!.helloWorld);

Anpassung

Aktualisierungsverhalten

OTA-Übersetzungen werden jedes Mal aktualisiert, wenn die App gestartet wird. Um dies zu deaktivieren:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", 
    checkForUpdates: false);

Manuelle Aktualisierung:

Phrase.updateTranslations(context).then((_) => print("Fertig!"));

Benutzerdefinierte App-Version

Das SDK verwendet standardmäßig die App-Version, um ein Release zurückzugeben, das den Release-Beschränkungen für die minimale und maximale Version entspricht. Die App-Version muss semantische Versionierung verwenden, andernfalls wird kein Übersetzungsupdate zurückgegeben. Falls die App keine semantische Versionierung verwendet, kann die App-Version manuell überschrieben werden: Es ist möglich, die App-Version manuell zu überschreiben:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]",
    customAppVersion: "1.2.3");

Konfiguriere das US-Datencenter

Das Phrase US-Datencenter wird ebenfalls unterstützt. Das US-Datencenter kann ausgewählt werden, indem der relevante API-Hostname-Parameter in der SDK-Konfiguration übergeben wird:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", host: PhraseHost.us);

Beispiel-App

https://github.com/phrase/flutter_sdk_example

Mit dem SDK überprüft die App regelmäßig auf aktualisierte Übersetzungen und lädt diese im Hintergrund herunter.

Mac Catalyst wird ebenfalls unterstützt.

Das SDK kann manuell oder über Swift Package Manager, Carthage oder Cocoa Pods installiert werden.

Falls Übersetzungen nicht aktualisiert werden:

Falls die falsche Version einer Übersetzung verwendet wird, stelle sicher, dass ein Release mit den neuesten Übersetzungen und der aktuellen App-Version verfügbar ist.

Swift Package Manager

Füge die öffentliche Repository-URL hinzu (https://github.com/phrase/ios-sdk/). Xcode übernimmt den Rest der Installation automatisch.

Carthage

Füge die folgende Zeile in deinen Cartfile ein:

binary "https://raw.githubusercontent.com/phrase/ios-sdk/master/PhraseSDK.json" ~> 3.0.0

Führe carthage update aus und füge das PhraseApp.framework zu deinem Projekt hinzu, wie in der Carthage-Dokumentation beschrieben.

Cocoa Pods

Füge die folgende Zeile in dein Podfile ein:

pod 'PhraseSDK'

Führe pod install aus. Falls du neu bei CocoaPods bist, sieh dir deren Dokumentation an.

Manuelle Installation

Befolge diese Schritte:

Konfiguration

Es wird empfohlen, beide Funktionen innerhalb des AppDelegate in der Methode applicationDidFinishLaunchingWithOptions aufzurufen.

Objective-C

Integriere das SDK in die Objective-C-Anwendung:

@import PhraseSDK;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [[Phrase shared] setDebugMode:true]; // Optional

  [[Phrase shared] setupWithDistributionID:@"Your Distribution ID"
                         environmentSecret:@"Your Environment Secret"];

  // ODER:
  //
  //  [[Phrase shared] setupWithDistributionID:@"Deine Distribution ID"
  //                         environmentSecret:@"Dein Environment Secret"
  //                                   timeout:10];

  // Aktualisiere Übersetzungen mit Callback-Block:
  [[Phrase shared] updateTranslationsWithCompletionHandler:^(BOOL updated, NSError* error){
    NSLog(@"Aktualisiert: %@", updated ? @"true" : @"false");

    if (error) {
      NSLog(@"Domain: %@ Code: %ld Nachricht: %@", error.domain, (long)error.code, error.localizedDescription);
    } else {
      NSLog(@"Kein Fehler");
    }

    // Übersetze über Bundle-Proxy:
    NSString *translation = NSLocalizedString(@"layouts.application.about", @"");
    NSLog(@"NSLocalizedString über Bundle-Proxy: %@", translation);

    // ODER:
    //
    // Übersetze mit Fallback-Methode:
    NSString *otherTranslation = [[Phrase shared]
                                  localizedStringForKey:@"layouts.application.about" value:NULL table:NULL];
    NSLog(@"Phrase.shared localizedStringForKey: %@", otherTranslation);
  }];

  // ODER:
  //
  // [[Phrase shared] updateTranslationsWithCompletionHandler:NULL]; // Ergebnis und Fehler ignorieren (nicht empfohlen)

  // [...] Dein anderer Code
  
  return YES;
}

Swizzling deaktivieren

Um Swizzling zu deaktivieren, setze PhraseSDKMainBundleProxyDisabled auf YES in der Info.plist Datei.

Wenn Swizzling deaktiviert ist, werden aktualisierte Übersetzungen nicht mehr angezeigt. Die Übersetzung wird immer noch synchronisiert, wenn updateTranslation aufgerufen wird und kann mit der Phrase.localizedString() Methode abgerufen werden.

App-Version-Verwaltung

Um zu bestimmen, welche Version zurückgegeben werden soll, benötigt das SDK eine semantische Version der App, damit Übersetzungen aktualisiert werden.

Das SDK versucht, eine semantische Version auf folgende Weise zu erhalten:

Wenn CFBundleShortVersionString fehlt oder nicht zusammen mit CFBundleVersion mit einer semantischen Version erstellt werden kann, wirft das SDK die PhraseSetupError.appVersionNotSemantic Nachricht.

Deaktivieren der Übersetzung für mehrere Tabellen

Um zu verhindern, dass OTA andere Tabellen im Haupt-iOS-Bundle übersetzt als die Standard-Localizable-Tabelle, setze die folgende Option:

Phrase.shared.configuration.ignoreOtherTables = true

Callbacks

Einen Callback-Handler anhängen, um erfolgreiche Übersetzungsaktualisierungen zu verarbeiten:

Phrase.shared.updateTranslation { result in
            switch result {
            case .success(let updated):
            case .failure:
            }
        }

Debug-Modus

Falls weitere Informationen benötigt werden, aktiviere den Debug-Modus, um zusätzliche Protokollierungen des PhraseSDK.framework in die Konsole zu erhalten:

Phrase.shared.configuration.debugMode = true

Timeout für Anfragen festlegen

Setze ein Timeout für die Anfragen an Phrase, indem du folgendes aufrufst:

Phrase.shared.configuration.timeout = TimeInterval(20)

Das Standard-Timeout beträgt 10 Sekunden und Verbindungen, die länger als 10 Sekunden dauern, werden geschlossen.

Manuelle Sprachüberschreibung bereitstellen

Falls du nicht die Systemsprache als Sprache verwendest, kann im Init-Aufruf eine andere Sprache festgelegt werden. Der Sprachcode muss in einer Veröffentlichung von Phrase vorhanden sein:

Phrase.shared.configuration.localeOverride = "en-US"

Fallback

Falls neue Übersetzungen nicht über das SDK von Phrase abgerufen werden können, werden die neuesten Übersetzungsdateien, die die Installation erhalten hat, verwendet. Falls die App nie neue Dateien von Phrase erhalten hat, werden die kompilierten Übersetzungsdateien der App verwendet. Dies verhindert Fehler bei technischen Schwierigkeiten oder Netzwerkfehlern. Es wird empfohlen, deine kompilierten Übersetzungsdateien in der App mit jeder Veröffentlichung auf dem neuesten Stand zu halten.

Prüfung

Das SDK ist Closed Source und kann nicht eingesehen oder modifiziert werden. Falls es eine Anforderung der Organisation ist, können Prüfungen bereitgestellt werden. Kontaktiere uns für weitere Details, falls erforderlich.

Mit dem SDK überprüft die App regelmäßig auf aktualisierte Übersetzungen und lädt diese im Hintergrund herunter.

Die Bibliothek für OTA-Übersetzungen funktioniert nur mit der react-i18next-Bibliothek.

Um das React Native SDK zu installieren, folge diesen Schritten:

Beispiel i18next.js Datei

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import ChainedBackend from "i18next-chained-backend";
import resourcesToBackend from "i18next-resources-to-backend";
import translationEN from "./locales/en/translation.json";
import translationRU from "./locales/ru/translation.json";
import Phrase from "react-native-phrase-sdk";

const localResources = {
  en: {
    translation: translationEN,
  },
  ru: {
    translation: translationRU,
  },
};

let phrase = new Phrase(
    "YOUR_DISTRIBUTION_ID",
    "YOUR_ENVIRONMENT_ID",
    require('./package.json').version,
    "i18next"
);

const backendPhrase = resourcesToBackend((language, namespace, callback) => {
    phrase.requestTranslation(language)
        .then((remoteResources) => {
            callback(null, remoteResources);
        })
        .catch((error) => {
            callback(error, null);
        });
});

const backendFallback = resourcesToBackend(localResources)

i18n
  .use(ChainedBackend)
  .use(initReactI18next)
  .init({
    backend: {
        backends: [backendPhrase, backendFallback]
    },
    debug: true,
    lng: "en",
    fallbackLng: "en",
    interpolation: {
      escapeValue: false, // nicht nötig für React, da es standardmäßig escaped
    }
  });

Beispiel-App

https://github.com/phrase/react_native_sdk_example

Die i18next-phrase-backend Bibliothek implementiert ein Beispiel-Backend für i18next, das die Übersetzungen von OTA-Veröffentlichungen abruft.

Um eine neue Veröffentlichung zu erstellen, muss die i18next Plattform für die Distribution eingestellt und Teil einer Veröffentlichung sein.

Verwendung

Um Phrase zu initialisieren:

import i18n from "i18next";
import { I18nextPhraseBackend } from "@phrase/i18next-backend";

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribution: 'DISTRIBUTION_ID',
      secret: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
    }
  });

Caching

Die Bibliothek speichert Übersetzungen im Cache und überprüft für 5 Minuten nicht auf neue Übersetzungen. Caching kann konfiguriert werden, indem die Option cacheExpirationTime in der Backend-Konfiguration zu Testzwecken gesetzt wird.

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribution: 'DISTRIBUTION_ID',
      secret: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
      cacheExpirationTime: 60 * 5, // Zeit in Sekunden
    }
  });

Beispiel-App

https://github.com/phrase/ota-web-demo

Die phrase-ota-i18n Bibliothek implementiert ein Beispiel-Backend für das I18n gem, das die Übersetzungen von OTA-Releases abruft. Mit der Bibliothek überprüft die Anwendung regelmäßig auf aktualisierte Übersetzungen und lädt sie im Hintergrund herunter.

Die Bibliothek ist für jede Ruby-Anwendung gültig, die das i18n gem verwendet.

Um ein neues Release zu erstellen, muss die Rails Plattform für die Distribution festgelegt und Teil eines Releases sein.

Installation

Verwendung

Um die Konfiguration zu generieren:

bundle exec rails generate phrase_ota:install --distribution-id <DISTRIBUTION_ID> --secret-token <SECRET>

Fehlersuche

Das gem hat eine Debug-Konfiguration, die im Initializer aktiviert werden kann:

config.debug = true