organize element documentation (#876) [deploy site]

Co-authored-by: Diego Molina <[email protected]>

Author: titusfortner

website_and_docs/content/documentation/test_practices/encouraged/locators.en.md

@@ -0,0 +1,34 @@
+---
+title: "Tips on working with locators"
+linkTitle: "Locators"
+weight: 8
+description: >
+    When to use which locators and how best to manage them in your code.
+---
+
+Take a look at examples of the [supported locator strategies]({{< ref "/documentation/webdriver/elements/locators.md" >}}).
+
+In general, if HTML IDs are available, unique, and consistently
+predictable, they are the preferred method for locating an element on
+a page. They tend to work very quickly, and forego much processing
+that comes with complicated DOM traversals.
+
+If unique IDs are unavailable, a well-written CSS selector is the
+preferred method of locating an element. XPath works as well as CSS
+selectors, but the syntax is complicated and frequently difficult to
+debug. Though XPath selectors are very flexible, they are typically
+not performance tested by browser vendors and tend to be quite slow.
+
+Selection strategies based on _linkText_ and _partialLinkText_ have
+drawbacks in that they only work on link elements. Additionally, they
+call down to XPath selectors internally in WebDriver.
+
+Tag name can be a dangerous way to locate elements. There are
+frequently multiple elements of the same tag present on the page.
+This is mostly useful when calling the _findElements(By)_ method which
+returns a collection of elements.
+
+The recommendation is to keep your locators as compact and
+readable as possible. Asking WebDriver to traverse the DOM structure
+is an expensive operation, and the more you can narrow the scope of
+your search, the better.

website_and_docs/content/documentation/test_practices/encouraged/locators.ja.md

@@ -0,0 +1,27 @@
+---
+title: "Tips on working with locators"
+linkTitle: "Locators"
+weight: 8
+needsTranslation: true
+description: >
+    When to use which locators and how best to manage them in your code.
+---
+
+Take a look at examples of the [supported locator strategies]({{< ref "/documentation/webdriver/elements/locators.md" >}}).
+
+一般に、HTMLのid属性が利用可能でユニークかつ一貫している場合、ページで要素を探す方法として適しています。
+idは動作がとても速い傾向があり、複雑なDOMトラバースに伴う処理を省略できます。
+
+ユニークなidが使えない場合、きれいに書かれたCSSセレクタが要素を探す方法として適しています。
+XPathはCSSセレクタと同様に動作しますが、シンタックスは複雑で大抵の場合デバッグが困難です。
+XPathはとても柔軟ですが、ブラウザベンダは性能テストを通常行っておらず、非常に動作が遅い傾向があります。
+
+link textセレクタとpartial _linkText_ セレクタはa要素でしか動作しないという欠点があります。
+加えて、これらはWebDriverの内部でXPathの呼び出しに置き換えられます。
+
+タグ名によるロケータは危険な方法になり得ます。
+大抵の場合ページ上には同じタグ名の要素が複数あります。タグ名は要素のコレクションを返す _findElements(By)_ メソッドを使う時にもっとも役に立ちます。
+
+ロケータは可能な限り簡潔に、読みやすい状態を保つことを推奨します。
+WebDriverでDOM構造のトラバースを行うのは重い処理となります。
+検索の範囲を狭めた方がより良い結果を得られます。

website_and_docs/content/documentation/test_practices/encouraged/locators.pt-br.md

@@ -0,0 +1,34 @@
+---
+title: "Tips on working with locators"
+linkTitle: "Locators"
+weight: 8
+needsTranslation: true
+description: >
+    When to use which locators and how best to manage them in your code.
+---
+
+Take a look at examples of the [supported locator strategies]({{< ref "/documentation/webdriver/elements/locators.md" >}}).
+
+No geral, se os IDs de HTML estiverem disponíveis, únicos e consistentemente
+previsíveis, eles são o método preferido para localizar um elemento
+uma página. Eles tendem a trabalhar muito rapidamente e dispensar muito processamento
+que vem com travessias de DOM complicadas.
+
+Se IDs exclusivos não estiverem disponíveis, um seletor CSS bem escrito é o
+método preferido de localização de um elemento. XPath funciona bem como CSS
+seletores, mas a sintaxe é complicada e frequentemente difícil de
+depurar. Embora os seletores XPath sejam muito flexíveis, eles não são tipicamente testados em performance por fornecedores de navegadores e tendem a ser bastante lentos.
+
+As estratégias de seleção baseadas em _linkText_ e _partialLinkText_ têm
+desvantagens porque eles só funcionam em elementos de link. Além disso, eles
+chamam seletores XPath internamente no WebDriver.
+
+O nome da tag pode ser uma maneira perigosa de localizar elementos. tem
+frequentemente, vários elementos da mesma tag presentes na página.
+Isso é útil principalmente ao chamar o método _findElements(By) _ que
+retorna uma coleção de elementos.
+
+A recomendação é manter seus localizadores compactos e
+legíveis quanto possível. Pedir ao WebDriver para percorrer a estrutura DOM
+é uma operação cara, e quanto mais você pode restringir o escopo de
+sua pesquisa, melhor.

website_and_docs/content/documentation/test_practices/encouraged/locators.zh-cn.md

@@ -0,0 +1,20 @@
+---
+title: "Tips on working with locators"
+linkTitle: "Locators"
+weight: 8
+needsTranslation: true
+description: >
+    When to use which locators and how best to manage them in your code.
+---
+
+Take a look at examples of the [supported locator strategies]({{< ref "/documentation/webdriver/elements/locators.md" >}}).
+
+一般来说，如果 HTML 的 id 是可用的、唯一的且是可预测的，那么它就是在页面上定位元素的首选方法。它们的工作速度非常快，可以避免复杂的 DOM 遍历带来的大量处理。
+
+如果没有唯一的 id，那么最好使用写得好的 CSS 选择器来查找元素。XPath 和 CSS 选择器一样好用，但是它语法很复杂，并且经常很难调试。尽管 XPath 选择器非常灵活，但是他们通常未经过浏览器厂商的性能测试，并且运行速度很慢。
+
+基于链接文本和部分链接文本的选择策略有其缺点，即只能对链接元素起作用。此外，它们在 WebDriver 内部调用 XPath 选择器。
+
+标签名可能是一种危险的定位元素的方法。页面上经常出现同一标签的多个元素。这在调用 _findElements(By)_ 方法返回元素集合的时候非常有用。
+
+建议您尽可能保持定位器的紧凑性和可读性。使用 WebDriver 遍历 DOM 结构是一项性能花销很大的操作，搜索范围越小越好。