Om du vill validera platshållarna i en översättning på din Mac jämför du varje arguments position, typ och avsedda användning med källmeddelandet. Använd Xcodes diagnostik för avvikelser, granska sedan pluralersättningar och testa den renderade etiketten med olika exempelvärden.

Den här guiden är avsedd för den som granskar en Mac-apps lokaliserade etiketter i Xcode. Uppgiften är att kontrollera ett meddelande och dess översättningar mot de värden som appen skickar in. Alla etiketter nedan är syntetiska engelska exempel; de illustrerar formateringsmekanik snarare än faktiska översättningar.

Vad ingår i ett meddelandes argumentkontrakt?

Ett argumentkontrakt är en granskningsanteckning som beskriver vilka värden ett meddelande tar emot: deras positioner, formateringstyper, betydelser och förväntade användning. Det är en praktisk checklista som härleds från källkoden och katalogen, inte ett separat Apple-filformat.

Swifts String.LocalizationValue stöder lokaliserbara strängar med interpolerade körningsvärden. Dokumentationen skiljer också mellan att använda källtexten som lokaliseringsnyckel och att ange en separat nyckel och ett standardvärde. Därför behöver en identifierare ensam inte visa vilka argument meddelandet har: granska standardkälltexten och dess anropsställe. String.LocalizationValue

Tänk på formatsträngen Added %lld items to %@. I det här exemplet skickar appen först ett heltal och sedan en objektbaserad samlingsetikett. Skriv ned kontraktet innan du redigerar översättningen:

Argumentposition Betydelse Förväntat format Exempelvärde
1 Antal tillagda objekt %lld 7
2 Etikett för målsamlingen %@ Canvas

Apples formatreferens definierar %@ som en objektkonvertering, %d som ett signerat 32-bitars heltal, %f som en double-konvertering och ll som heltalslängdmodifieraren för long long. Den dokumenterar också positionsformer som %1$@. Bevara den fullständiga typinformationen; om du ändrar %lld till %d ändras den förväntade heltalstypen. Referensen är arkiverad, så använd den för formatsyntax tillsammans med aktuell katalogdokumentation. String Format Specifiers

Lägg till argumentens betydelser i granskningsanteckningen även när de har samma typ. För Moved %@ to %@ kan en typkontroll inte skilja objektetiketten från destinationsetiketten. Korrekt syntax måste också bevara sambandet mellan värden och ord.

Hur hittar du den auktoritativa källan i Xcode?

Börja med att öppna projektet i Xcode och hitta katalogen som innehåller meddelandet. Om källan har ändrats väljer du Product > Build för att uppdatera de extraherade strängarna. Markera katalogen i projektnavigatorn, välj Editor > Assistant och markera meddelandenyckeln för att visa dess källa. Apple dokumenterar det här arbetsflödet för att hitta och uppdatera katalogposter. Localizing and varying text with a string catalog

Kontrollera vilka värden anropsstället faktiskt skickar, i vilken ordning och via vilket lokaliserings-API. Apple rekommenderar lokaliseringsbara API:er som String(localized:); en initializer med ett separat defaultValue använder sin första parameter som nyckel och sin andra som standardkällsträng. Det spelar roll när ett neutralt id som collection.added.summary äger meddelandet. Preparing your app’s text for translation

Anteckna tre saker tillsammans: katalogen och nyckeln, standardkällans formulering samt argumentens ordnade betydelser och typer. Om de inte stämmer överens ska du reda ut skillnaden innan du ändrar översättningarna. Annars kan du anpassa en översättning till en inaktuell källa i stället för till appens aktuella indata.

Ge också sammanhang för framtida ändringar. Apple stöder kommentarer för lokaliseringsbara strängar som förklarar hur de används. En användbar syntetisk kommentar skulle ange att argument 1 är objektantalet och argument 2 är etiketten för målsamlingen. Det ger den som lokaliserar information som en formatspecifierare inte kan uttrycka. Preparing your app’s text for translation

Hur kontrollerar du antal, typer och argumentpositioner?

Apple införde validering av strängkataloger för vanliga problem, bland annat avvikande formatspecifierare, med korrigeringar tillgängliga för vissa problem. Granska de diagnostikmeddelanden som Xcode visar för posten. Se en föreslagen korrigering som ett förslag på syntaxreparation och kontrollera att den bevarar meddelandets betydelse. Build multilingual-ready apps

Följ den här granskningsordningen för ett enkelt meddelande utan pluralersättningar:

  1. Identifiera varje platshållare som tar emot ett argument i källtexten och kandidattexten.
  2. Koppla varje platshållare till dess argumentposition.
  3. Jämför dess fullständiga formattyp med kontraktet.
  4. Kontrollera att varje obligatoriskt värde förekommer där formuleringen förutsätter det.
  5. Undersök tillagda, utelämnade eller upprepade referenser var för sig.

Positionsnotation gör att en översättning kan ändra ordföljd och ändå behålla argumentens identitet. I %2$@: added %1$lld items hänvisar den första synliga platshållaren till argument 2 och den andra till argument 1. Apple dokumenterar positionssyntaxen n$. String Format Specifiers

Följande beslutstabell gäller det illustrativa kontraktet med två argument ovan. Det här är föreslagna granskningsutfall, inte resultat från att ha kört Xcode:

Kandidatens formattext Granskningsutfall Orsak
Added %lld items to %@ Stämmer med det enkla kontraktet Antalet först, destinationen sedan
%2$@: added %1$lld items Stämmer efter omordning Explicita positioner bevarar båda argumentens identitet
Added %d items to %@ Korrigera heltalstypen Argument 1 använder inte längre den förväntade längdmodifieraren
Added %lld items Undersök utelämnandet Destinationen som meddelandet kräver saknas
Added %1$lld items to %1$@ Korrigera referenserna Argument 1 refereras med motstridiga typer; argument 2 saknas
Added %1$lld items to %2$@ (%2$@) Granska upprepningen Det finns tre förekomster men bara två olika refererade argument

Håll isär antalet förekomster och antalet olika argument. Den sista raden visar avsiktligt skillnaden: om argument 2 upprepas skapas inget tredje indatavärde. Om upprepningen passar i formuleringen är ett redaktionellt beslut. I den här uppgiften ska du flagga den tills dess syfte har klarlagts.

Räkna inte heller varje procenttecken som ett argument. Apple definierar %% som ett bokstavligt procenttecken. En formatetikett som Scale: %lld%% innehåller en värdeplatshållare och ett escapetecken för procent. String Format Specifiers

Varför kräver pluralersättningar en annan kontroll?

Plurala meddelanden kräver att du granskar både urvalsmekanismen och texten som visar ett värde. Under sin session om strängkataloger förklarar Apple att ersättningar kan innehålla ordlistor med pluralfall. Inspektorn visar det styrande argumentets position och C-formatsspecifikator. En ersättning kan därför bero på ett argument även när en viss gren inte skriver ut det argumentet numeriskt. Discover String Catalogs

För ett syntetiskt meddelande om antal objekt kan du jämföra One item added med %lld items added. Den första grenen skriver ut antalet med ord; den andra visar det som en siffra. En regel som kräver samma antal synliga platshållare i varje gren skulle i onödan underkänna den första. Apples dokumenterade beteende för strings-dictionary-formatet tillåter uttryckligen att den numeriska formatspecifikatorn utelämnas i pluralformer och anger att antalet kan skrivas ut med ord. Stringsdict file format

Använd i stället den här grenbaserade granskningen:

  • Kontrollera ersättningens styrande argumentposition och typ i inspektorn.
  • Granska alla pluralgrenar som finns för mållokaliseringen.
  • Jämför varje visad platshållare med argumentet den refererar till.
  • Förklara eventuell utelämnad siffervisning med grenens formulering.
  • Kontrollera andra argument i meddelandet separat; att skriva ut ett antal med ord förklarar inte varför en samlingsetikett saknas.

Bevara rollerna separat för två antal som varierar oberoende av varandra. Ett syntetiskt meddelande om objekt och samlingar behöver att objektantalet styr objektersättningen och att samlingsantalet styr samlingsersättningen. Apple dokumenterar flera ersättningar i ett meddelande och förklarar att körningsresultatet kombinerar de valda pluralfallen. Discover String Catalogs

Hur bekräftar du det korrigerade meddelandet på din Mac?

När du har korrigerat posten bygger du appen och granskar eventuella återstående diagnostikmeddelanden för katalogen. Kör sedan den aktuella skärmen med mållokaliseringen. Apples arbetsflöde är att välja Product > Scheme > Edit Scheme, markera Run, öppna Options, välja App Language och lämplig App Region, klicka på Close och köra det valda målet. Testing localizations when running your app

Välj exempelvärden som gör förväxlingar synliga. För två argument som räknar objekt använder du olika tal, till exempel 2 och 7. För två textargument använder du olika etiketter, till exempel Tile och Canvas. Det här är illustrativa testvärden; syftet är att visa vilket inskickat värde som visas i varje del av meddelandet.

För meddelanden med pluralformer testar du värden som leder till de grenar du granskar. När två ersättningar varierar oberoende av varandra tar du med kombinationer där det ena antalet ändras medan det andra hålls konstant. Granska både den valda formuleringen och placeringen av varje visat värde. En lyckad återgivning av en kombination innebär inte att de andra grenarna har granskats.

Håll översättningsstatusen åtskild från kontraktskontrollen. Apple beskriver katalogens gröna bock som statusen översatt när text har angetts. Anteckna de kontroller du faktiskt utförde—argumentkoppling, typjämförelse, granskning av grenar och exempel på renderad text—i stället för att behandla statusindikatorn som bevis på alla fyra. Localizing and varying text with a string catalog

Meddelandet är redo att gå vidare när dess platshållare motsvarar de avsedda argumenten, typerna stämmer och alla grenspecifika utelämnanden eller upprepningar har en tydlig förklaring. Om du håller det här kortfattade kontraktet intill meddelandet blir det lättare att bedöma nästa ändring av källan eller översättningen.

Källor