Merge pull request #739 from marionbarker/working-docs

Rework some translation tags

README.md

@@ -156,9 +156,9 @@ There are still some **issues**, where text is translated whereas it should not,
 
 To improve the automatic translation quality, please follow these rules when writing or updating the documentation. This will provide *Google Translate* with more context and enhance translation accuracy.
 
-#### Rules
+#### Suggestions
 
-Updates to Eric's comments (from Marion)
+Updates to Eric's suggestions (from Marion)
 
 Really - just saying the same thing in different words.
 
@@ -193,12 +193,20 @@ This is in the middle of a sentence that includes&nbsp;<span translate="no">Word
 ```
 If the word is at the end of a line or has other punctuation, the `&nbsp;` can be skipped:
 
-### All about&nbsp;<span translate="no">Word or Phrase</span>
+### All about&nbsp;<span translate="no">Word</span>
 
-This ability to build &nbsp;<span translate="no">Loop</span>, from both a browser and with Mac-Xcode, is wonderful.
+This ability to build&nbsp;<span translate="no">Loop</span>, from both a browser and with Mac-Xcode, is wonderful.
 ```
 
-These words / phrases **do not need** no-translate tags, however, they are typically rendered in italics anyway:
+Be warned that if `&nbsp;` is part of the text in a header, the automatic link doesn't acknowledge the space. The link above would be `#all-aboutword`, not `#all-about-word`.
+
+If you want italic font with `span`, I choose to use underscore instead of asterick to make the word show up as italic font because I think that helps with clarity (opinion only):
+```
+This ability to build&nbsp;_<span translate="no">Loop</span>_, from both a browser and with Mac-Xcode, is wonderful.
+```
+
+
+These words / phrases **do not need** no-translate tags, however, they are typically rendered in italics (use astericks on either side):
 
 * Xcode
 * Mac-Xcode
@@ -210,6 +218,12 @@ These words **do need** no-translate tags (most of the time):
 * Loop
 * LoopKit/Loop
 
+Look out for Loop showing up as buckle, at least in French and Spanish, in translations. That indicates `span` must be used, with the `&nbsp;` required if there is no punctuation mark. Once again, using underscore instead of asterisk in concert with `span` is a preference:
+
+```
+&nbsp;_<span translate="no">Loop</span>_&nbsp;
+```
+
 Common words like `Secrets` that will show up on `GitHub` for Building with Browser should be enclosed in `code` so tooltips will work and the word will be highlighted as important.
 
 From Eric (his rules before Marion made comments above)

docs/build/build-app.md

@@ -24,7 +24,7 @@ If you do watch this video, please note that you no longer are required to delet
 
 ## Build with Browser
 
-If you previously used [Build with Browser](../gh-actions/gh-overview.md) to install Loop on this phone, you must [Disable Automatic Install from&nbsp;<span translate="no">TestFlight</span>](../gh-actions/gh-deploy.md#disable-automatic-install-fromtestflight) or you will not be able to install on that phone with Xcode.
+If you previously used [Build with Browser](../gh-actions/gh-overview.md) to install Loop on this phone, you must [Disable Automatic Install from *TestFlight*](../gh-actions/gh-deploy.md#disable-automatic-install-from-testflight) or you will not be able to install on that phone with Xcode.
 
 ## Developer Mode
 

docs/build/code-customization.md

@@ -170,7 +170,7 @@ You can customize chart display settings if you want. The original lines of code
 
 The instructions on this page were originally prepared for the Mac-Xcode method. 
 
-The Build with Browser method instructions are similar, but each one is used edit a file using a browser in your&nbsp;<span translate="no">GitHub</span>&nbsp;account as instructed on the [Customize with Browser](../gh-actions/gh-customize.md) page.
+The Build with Browser method instructions are similar, but each one is used edit a file using a browser in your *GitHub* account as instructed on the [Customize with Browser](../gh-actions/gh-customize.md) page.
 
 For each customization, you will be given landmarks to find the correct location in the code. You can choose to search using the `Key_Phrase` or navigate to the file in the folder structure and look for ( ++cmd+l++ # ) the line number. 
 

docs/build/computer.md

@@ -14,7 +14,7 @@
 
     - You need a paid ($99/year)&nbsp;[<span translate="no">Apple Developer Account</span>](apple-developer.md)
     - You need an account (free) with&nbsp;[<span translate="no">GitHub</span>](https://github.com)
-    - You need a [compatible phone](phone.md) to install the app from&nbsp;<span translate="no">TestFlight</span>
+    - You need a [compatible phone](phone.md) to install the app from *TestFlight*
     - You need a [compatible Pump](pump.md) and [CGM](cgm.md) if you want to actually use the app (and not just explore the app)
 
 !!! abstract "Summary"
@@ -38,7 +38,7 @@ If you have access to a computer with MacOS 13.5 or newer, you can skip ahead to
 
 ## Compatible Versions
 
-The current development version and the next release of&nbsp;<span translate="no">Loop</span>&nbsp;will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use [Build with Browser](../gh-actions/gh-overview.md), which supports iOS 15, 16, and 17.
+The current development version and the next release of&nbsp;_<span translate="no">Loop</span>_&nbsp;will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use [Build with Browser](../gh-actions/gh-overview.md), which supports iOS 15, 16, and 17.
 
 When this page was last updated, macOS 14.0 and Xcode 15.0 were tested to successfully build the app for phones with iOS 15 through iOS 17.0.2.
 

docs/build/loop-data.md

@@ -36,7 +36,7 @@ Take some time to familiarize yourself with these data options and choose your p
     * For those who assist someone who is Looping, Nightscout enables the caregiver to provide remote commands to the Looper's phone
         * Loop 2 allows overrides to be enabled or disabled remotely
         * Loop 3 allows remote commands for carbs, bolus or overrides
-        * The &nbsp;[<span translate="no">Loop Caregiver</span>](../nightscout/loop-caregiver.md) app is under development, but already has sufficient capabilities to be useful for caregivers to monitor and provide remote commands to their Looper's phone
+        * The [*Loop Caregiver*](../nightscout/loop-caregiver.md) app is under development, but already has sufficient capabilities to be useful for caregivers to monitor and provide remote commands to their Looper's phone
 
 Nightscout options include free or nominal cost sites you build yourself or there are several Nightscout as a Service vendors who provide turn-key sites for a monthly fee. Links to the options are found in the [Nightscout: Documentation](https://nightscout.github.io/) - note that link takes you to a different site.
 

docs/build/xcode-version.md

@@ -77,7 +77,7 @@ After any update of [macOS](computer.md#check-your-macos-version) or Xcode, it i
 
 ### Compatible Versions#
 
-The current development version and the next release of&nbsp;<span translate="no">Loop</span>&nbsp;will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use [Build with Browser](../gh-actions/gh-overview.md), which supports iOS 15, 16, and 17.
+The current development version and the next release of&nbsp;_<span translate="no">Loop</span>_&nbsp;will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use [Build with Browser](../gh-actions/gh-overview.md), which supports iOS 15, 16, and 17.
 
 When this page was last updated, macOS 14.0 and Xcode 15.0 were tested to successfully build the app for phones with iOS 15 through iOS 17.0.2.
 

docs/faqs/algorithm-faqs.md

@@ -46,7 +46,7 @@ IOB is plotted on the [Active Insulin Chart](../loop-3/displays-v3.md#active-ins
 
 ## How do Delivery Limits Affect Automatic Dosing?
 
-With each cycle, <span translate="no">Loop</span>&nbsp;generates a glucose prediction and a recommended dose (positive or negative) to bring you to your correction range.
+With each cycle, _<span translate="no">Loop</span>_&nbsp;generates a glucose prediction and a recommended dose (positive or negative) to bring you to your correction range.
 
 * The nearest 3 hours has more influence on the recommendation than the later 3 hours, but the entire 6 hours is considered
 * The automated response to a negative recommended dose is to reduce basal rate, typically to zero